Before You Start
Access to Knak Admin settings
A translation tool that supports API workflows
Basic knowledge of API authentication
Set Up API Access
Create an API Role
Open Knak Builder
Click Admin (top left)
Click Company > Roles > + Create Role
Add Role Name: API User
Add Role Description (optional)
Add permissions:
Request Translations
Can Manage API Tokens
(Optional) Request Translations for Unapproved Email
Click Create
Create an API User
Click Company > Users > Invite User
Enter user details:
Email
First name
Last name
Select the API role you created
Click Save User and Send Invite
💡 Tip: Use an email alias when setting up integrations (for example, youremail+api@domain.com).
This keeps all integrations tied to one dedicated account. It also prevents disruptions if a team member leaves.
Authentication
To allow your platform to access data in Knak, we recommend using a permanent API key. When creating an API key, make sure to use the API User created earlier. You can generate API keys here: https://enterprise.knak.io/account/api-access
For information on how to use API tokens when making requests against the Knak API, see https://enterprise.knak.io/docs/api#section/Overview/Authentication
Create a Webhook
Webhooks allow events in Knak to trigger an HTTP request to be sent to an endpoint of your choice containing information about the event. For a custom MAP integration, we want to listen for the syncRequested event, which will notify us when we need to pull asset content from Knak.
This process can be performed by any user who has permission to manage integrations.
Open Knak Builder and navigate to Admin (top left button).
Navigate to Integrations > Webhooks
3. Enter a name, Payload URL, Secret and Subscribed Events (e.g. syncRequested), then click Save.
Note: The secret field is used for security purposes to verify the authenticity of the webhook payload. The payload is hashed using the HMAC SHA256 algorithm using this secret. You can either use the automatically generated string or regenerate it by clicking the refresh icon. The field is hidden by default, but you can reveal it by clicking the reveal icon, allowing you to copy its contents. You will need this secret in a later step.
Create a Custom MAP Integration in Knak
Adding an Integration will allow Users to sync assets to this integration under the publish menu.
Open Knak Builder and navigate to Admin (top left button).
Navigate to Integrations > Platforms > + Add New Integration, then select Connect under CUSTOM MAP.
Enter an Integration Name, select Asset Sync Types (Email, Landing Page, or Both), and Merge Tag Platform Format, then click Create New Integration.
Managing your integration
Now that your integration is set up, you can view its configuration, edit it, or delete it from the "My Platform Connection" list on the Integrations page.
If you need to connect a new integration – or re-add a previously deleted one – you can do so by scrolling down to the "All Platforms" section and clicking Connect or Add Another Connection on the relevant platform tile.
Sync an Asset
Next, we will be discussing how to sync an asset to your platform via Knak’s public API. We will go over what’s contained in webhook payloads and necessary requests along with their responses.
Sync Requested Webhook
Now that the sync has been initiated, the syncRequested Webhook will be broadcast with the following payload:
Verifying Webhook Payload Authenticity
In order to verify the authenticity of the payload, you can calculate the HMAC (SHA256) hash of the payload using the secret generated earlier, and then compare it to the signature included in the Knak-Signature header. If the calculated hash matches the signature, then you can be confident that the payload has not been tampered with and is OK to process.
Fetch Asset Content
You can fetch the asset’s content by sending a GET request to the content_link URL from the syncRequest webhook payload. The response will contain the asset’s metadata, HTML and plain text content.
Optionally, you can pass a platform parameter to convert the asset contents to its platform specific syntax. The content_link attribute will contain the platform parameter matching the Integration used to initiate the sync event.
Sample Request
Request Parameters
Parameter | Required | Example | Description |
platform | No | Marketo | Merge tags in the HTML and text properties will be converted to the specified platform syntax |
Response
Now that you have the asset’s content, you can create or update the asset in your platform.
Update Sync Status
Now that you attempted to create or update the asset in your platform, you will want to update the sync status in Knak. This will allow you to access the asset from Knak via a link, log error messages, resync, and see the sync progress in real-time.
Sample Request
Request Body
When a status is set to completed, you should include the map_id property in the payload. This is the unique ID of the asset in your custom platform. Knak will use this to determine whether the Asset can be re-synced, and also include this in any subsequent syncRequested events for your convenience. The map_url property can also be set, which will be shown to the Knak user in the re-sync prompt.
When a status is set to failed, we recommend including the error_message property. When this is specified, it is shown to the Knak User, and logged to the database for debugging.
Completed UI State
The sync modal will update when the sync_status is set to completed.
Since the sync was successful, you can now resync via the Publish menu.
Failed UI State
The sync modal will update when the sync_status is set to failed. The error_message property is displayed in the UI.
Next Steps
That’s it! You have successfully configured an integration with your custom platform! You can refer to our API documentation for more details.
Need more help? Contact support via live chat within Knak using the chat bubble in the bottom right corner or email support@knak.com.