Inbound Webhooks

Inbound webhooks allow external systems to notify CampaignLark of contact-related events, automatically managing contacts in your audience.

Overview

Inbound webhooks are unique URLs tied to your workspace. When an external system sends a request to a webhook URL, CampaignLark processes it and performs the corresponding action on the matching contact.

Getting Started

To set up an inbound webhook:

1. Navigate to your workspace settings
2. Select the Inbound Webhooks section
3. Click Create Webhook
4. Provide a name (max 64 characters)
5. Select a webhook type
6. Optionally assign tags (available for SUBSCRIBED and UNCONFIRMED types only)
7. Save — your unique webhook URL will be generated automatically

Your webhook URL will be in the format:

https://api.campaignlark.com/v1/inbound-webhooks/<hash>

Webhook Types

Each inbound webhook has a type that determines what action is performed when triggered:

Type	Description
SUBSCRIBED	Creates a new contact (or updates an existing one) and sets their status to Subscribed. Triggers the Contact Subscribed (Confirmed) automation event.
UNCONFIRMED	Creates a new contact (or updates an existing one) and sets their status to Unconfirmed. Triggers the Contact Subscribed (Pending) automation event.
UNSUBSCRIBED	Finds the contact by email and sets their status to Unsubscribed. Triggers the Contact Unsubscribed automation event.
DELETE	Finds the contact by email and permanently deletes them from the workspace.

Sending a Request

Inbound webhooks accept both GET and POST requests. The webhook endpoint is:

GET  https://api.campaignlark.com/v1/inbound-webhooks/<hash>

POST https://api.campaignlark.com/v1/inbound-webhooks/<hash>

Supported Content Types

For POST requests, the following content types are accepted:

• application/json
• application/x-www-form-urlencoded
• multipart/form-data

For GET requests, data is read from query string parameters.

Required Fields

The email_address field is required in all webhook payloads. This is used to identify or create the contact.

{
  "email_address": "tywin@example.com"
}

Additional Fields

Any additional fields in the payload that match a workspace merge tag will be mapped to the corresponding contact field. For example:

{
  "email_address": "cersei@example.com",
  "first_name": "Cersei",
  "last_name": "Lannister"
}

Fields with no matching merge tag are silently ignored. Fields with a configured default value will use the default if not provided.

Tags

Webhooks of type SUBSCRIBED or UNCONFIRMED can have tags pre-configured. When the webhook is triggered, those tags are automatically applied to the contact.

Tags cannot be configured on UNSUBSCRIBED or DELETE webhook types.

Response

On success, the webhook returns HTTP 200 with:

{
  "success": true,
  "message": "Acknowledged. The webhook has been processed."
}

On failure (e.g. missing email, contact not found, invalid webhook hash), it returns HTTP 400 or 404 with:

{
  "success": false,
  "message": "<reason for failure>"
}

Common Error Conditions

Error	Cause
Please provide an email address in the webhook data.	The email_address field is missing or empty.
It looks like the webhook you're trying to access doesn't exist.	The hash in the URL does not match any configured webhook.
We were unable to find the contact.	UNSUBSCRIBED or DELETE type — no contact with that email exists.
Please provide a valid email address	The provided email fails validation.

Behavior Details

• Existing contact on SUBSCRIBED: The contact's status is updated to SUBSCRIBED and tags are applied. The confirmed automation event fires only if the status was previously not SUBSCRIBED.
• Existing contact on UNCONFIRMED: The contact's status is updated to UNCONFIRMED and tags are applied. The pending automation event always fires.
• New contact on SUBSCRIBED or UNCONFIRMED: A new contact is created with fields populated from the payload, and the corresponding automation event fires.
• Segment recalculation: After any successful webhook processing, segment membership is recalculated in the background.