Skip to main content

Setting Up a Custom MAP Integration

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

Before You Start

  • Access to Knak Admin settings

  • A translation tool that supports API workflows

  • Basic knowledge of API authentication

For complete endpoint details, request examples, and response schemas, see the Knak API documentation.

Set Up API Access

Create an API Role

  1. Open Knak Builder

  2. Click Admin (top left)

  3. Click Company > Roles > + Create Role

    Roles page and create role button

  4. Add Role Name: API User

  5. Add Role Description (optional)

  6. Add permissions:

    • Request Translations

    • Can Manage API Tokens

    • (Optional) Request Translations for Unapproved Email

  7. Click Create

    Role permission selection screen

Create an API User

  1. Click Company > Users > Invite User

    Invite user screen

  2. Enter user details:

    • Email

    • First name

    • Last name

  3. Select the API role you created

  4. Click Save User and Send Invite

    Inviting an API user to Knak.

💡 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.

Create an API Token

Use a permanent API token to authenticate requests from your platform.

  1. Sign in as the API user you created.

  2. Open the API Access page.

    API tokens page in Knak admin section.

  3. Click +Create New Token to generate a permanent API token.

  4. Name the API token.

  5. Copy and store the token securely.

    Personal Access Token popup modal.

For authentication details, see the API Authentication documentation.

⚠️ Important: The Personal Access Token is only displayed once. After you close this window, you cannot view it again. Store the token in a secure location before leaving the page. You will use this token to authenticate API requests to Knak.

Create a Webhook

A webhook sends an HTTP request whenever an event occurs in Knak.

For a custom MAP integration, subscribe to the syncRequested event. This event tells your platform when to retrieve asset content.

Note: You must have permission to manage integrations.

Configure the Webhook

  1. Open Knak Builder.

  2. Click Admin.

  3. Go to Integrations > Webhooks.

  4. Click Create Webhook.

    Webhooks page with "Create Webhook" option highlighted.

  5. Enter the following:

    • Name

    • Payload URL

    • Secret

    • Subscribed Events: syncRequested

  6. Click Create new webhook.

About the Webhook Secret

The webhook secret verifies that requests came from Knak.

  • Knak signs each payload using the HMAC SHA256 algorithm.

  • Compare the generated hash with the value in the Knak-Signature request header.

  • Process the webhook only if both values match.

You can:

  • Use the automatically generated secret.

  • Generate a new secret with the refresh icon.

  • Click the Eye icon to reveal the webhook secret. Copy the value and store it securely for use when validating webhook requests.

    Eye icon highlighted in the create webhook screen.

Note: Keep this secret safe. You will use it when validating webhook requests.

Create a Custom MAP Integration

Create a platform connection so users can publish assets from Knak.

  1. Open Knak Builder.

  2. Click Admin.

  3. Go to Integrations > Platforms.

    Integrations > Platforms navigation in the admin side of Knak.

  4. Navigate to the Custom Marketing Automation Platform tile under the Marketing Automation Platforms section.

  5. Click the Connect button.

  6. Enter:

    • Integration Name

    • Asset Sync Types

      • Email

      • Landing Page

      • Both

    • Merge Tag Platform Format

  7. Click Create New Integration.

    Custom Marketing Automation Platform Integration settings screen.

Manage Your Integration

After setup, view your integration in the My Platform Connection list on the Integrations page.

From here, you can:

  • View the configuration

  • Edit the integration

  • Delete the integration

    My Platform Connections section.

To connect a new integration or re-add a deleted one:

  1. Scroll to All Platforms.

  2. Find the Custom Marketing Automation Platform tile.

  3. Click Connect or Add Another Connection.

    Add Another Connection button highlighted on the Custom Marketing Automation Platforms integration tile.

Sync an Asset

After your integration is configured, you can sync assets from Knak to your custom platform.

Start the Sync

  1. Open the asset you want to sync.

  2. Click the Actions menu.

  3. Select Sync.

    Actions menu with the sync option highlighted.

  4. Choose your Custom Marketing Automation Platform integration.

    Select an integration menu during sync process.

  5. Click Sync.

  6. Knak starts the sync process and sends a syncRequested webhook to your configured endpoint.

    Syncing email progress bar.

The sync process includes these steps:

  1. Receive the syncRequested webhook.

  2. Validate the webhook signature.

  3. Retrieve the asset content.

  4. Create or update the asset in your platform.

  5. Update the sync status in Knak.

Receive the syncRequested Webhook

When you start a sync, Knak sends a syncRequested webhook to your configured endpoint.

The payload includes information such as:

  • Asset identifiers

  • Sync status identifier

  • Content URL (content_link)

  • Platform information

See the API documentation for the complete webhook payload schema:

https://enterprise.knak.io/docs/api#tag/asset.sync_requested

Verify the Webhook

Before processing the request:

  1. Calculate the HMAC SHA256 hash using your webhook secret.

  2. Compare the result with the Knak-Signature header.

  3. Continue only if both values match.

This confirms the payload has not been modified.

Retrieve Asset Content

Send a GET request to the content_link included in the webhook.

The response contains:

  • Asset metadata

  • HTML

  • Plain text

Optional Platform Conversion

You can include the optional platform parameter. When provided, Knak converts merge tags into the syntax required by your platform.

Parameter

Required

Description

platform

No

Converts merge tags to your platform's syntax. Example: Marketo.

Sample Request

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

For request parameters, response fields, and additional examples, see the Get Asset Content API documentation:

https://enterprise.knak.io/docs/api#tag/Assets/paths/~1assets~1{asset_id}~1content/get

Update the Sync Status

After processing the asset, update the sync status by sending a PATCH request to the Sync Status endpoint.

Sample Request

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

When the Sync Succeeds

Set the status to completed.

Property

Required

Purpose

map_id

Yes

Unique identifier of the asset in your platform.

map_url

Optional

Link to the asset in your platform.

Knak stores the map_id for future syncs. If you include a map_url, users can open the synced asset directly from Knak.

When the Sync Fails

Set the status to failed.

Property

Recommended

Purpose

error_message

Yes

Displays the error to users. Stores the error for troubleshooting.

For the complete request body, supported status values, and response examples, see the Update Sync Status API documentation:

https://enterprise.knak.io/docs/api#tag/SyncStatuses/paths/~1sync-statuses~1{sync_status_id}/patch

Related API Documentation

Need more help? Contact support via live chat within Knak using the chat bubble in the bottom right corner or email support@knak.com.

Related Articles
Did this answer your question?