Custom MAP Integration Guide

The process of creating an API user, authentication, creating a Custom MAP Integration, setting up Webhooks, and syncing to your platform.

High level flow

A custom MAP integration comprises the following elements:

• Configuration in Knak which allows the Knak user to initiate a sync from Knak to the MAP integration
• Your custom webservice which:
  • receives a webhook notification that a sync has been requested
  • fetches the asset content from Knak
  • performs the necessary actions to sync the asset to the MAP
  • updates Knak with the result of the sync (success / failure)

The sequence diagram below shows how user interactions (KnakUi), the Knak API (KnakEnterprise), and your webservice (MAP) interact.

Create an API User

Custom MAP integrations are often server-to-server integrations, so we recommend creating an API user and using an API key for authentication.

Follow the steps at Setting up an API User, making sure to include the Download Email permission.

Authentication

Use the API User created earlier. You can generate a new key at: https://enterprise.knak.io/account/api-access

Learn how to use API tokens in requests: Authentication Documentation

Create a Webhook

Webhooks let Knak trigger HTTP requests to your system. Use this to listen for the syncRequested event, which signals that a Knak user has requested that asset content needs to be synced from Knak to your platform.

1. Open Knak Builder and navigate to Admin

2. Go 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

This allows users to sync assets to this integration from the Publish menu.

1. Open Knak Builder and navigate to Admin

2. Go to Integrations > Platforms > + Add New Integration and select Connect under CUSTOM MAP

   

3. Enter:

   • Integration Name
   • Asset Sync Types (Email, Landing Page, or Both)
   • Merge Tag Platform Format

   Then click Create New Integration

   

Managing Your Integration

After setup, manage your connection in My Platform Connections from the Integrations page.

To add/re-add integrations, scroll to All Platforms and click Connect or Add Another Connection.

Sync an Asset

Now let’s sync an asset via Knak’s public API. This includes using webhook payloads and sending requests with responses.

Sync Requested Webhook

Once a sync is initiated, the syncRequested webhook sends a payload.

Learn more: Webhook Documentation

Verifying Webhook Payload Authenticity

Verify the HMAC SHA256 hash of the payload using your secret, then compare it to the Knak-Signature header.

Fetch Asset Content

GET request to the content_link URL returns:

• Metadata
• HTML content
• Plain text content

You can pass a platform parameter to format the content accordingly.

Example Request:

GET https://enterprise.knak.io/api/published/v1/assets/609d7ce223411/content

Request Parameters

Parameter	Required	Example	Description
platform	No	Marketo	Converts merge tags to platform syntax

Response

Learn more about the content response: Get Asset Content API

Update Sync Status

After processing the asset, update the sync status in Knak.

Example PATCH request:

PATCH https://enterprise.knak.io/api/published/v1/sync-status/609d7ce223411

More info: Update Sync Status API

• When setting status to completed, include:

  • map_id (your internal asset ID)
  • map_url (URL shown in Knak for re-sync)

• When setting status to failed, include:

  • error_message (shown in UI and logs)

  Caution

  After sending the SyncRequested event, Knak will wait 3 minutes for your service to update the sync status. If the status is not updated within 3 minutes, a message will be shown to the user indicating that the sync has failed.

Completed UI State

UI updates when status is set to completed.

Failed UI State

UI updates when status is set to failed, displaying the error message.

Next Steps

That’s it! You’ve configured a custom platform integration. Refer to our API documentation for more details.

Need help? Reach out via the chat bubble in Knak or email support@knak.com.