It’s easy to connect your platform to Knak using our public API. With this integration, you will be able to seamlessly access and manage your Knak data from within your own platform. Let's get started!
Create an API Role
Open Knak Builder and navigate to Admin (top left button).
2. Navigate to Company > Roles > + Create Role
3. Add the Download Email and Can Manage API Tokens permissions
4. Click Create.
Create an API User
1. Navigate to Company > Users > Invite User
2. Enter an Email, First name and Last name. A confirmation email will be sent to the provided email address. You can utilize the "+" convention (e.g. youremail+api@domain.com) for your email address.
3. In Select Roles add the role that was created above
4. Click Save User and Send Invite
More info here: https://help.knak.io/en/articles/1731519-add-remove-users
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 a 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 permissions 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 give Users the option 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.
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.