Overview

Webhooks automatically stream real-time event data from Cordial to external application APIs. You can enable multiple Webhooks, each configured to stream a specified set of system and/or custom events to an external endpoint. This enables you to set up your own near-real-time streaming integrations with third-party APIs or your own internal APIs.

Webhooks are highly useful for integration with APIs designed to ingest large volumes of event data. You can transform the Webhook payloads within Cordial to send properly-formatted data to any applicable API.

Create a Webhook

1. Log in to Cordial and navigate to Integrations > Webhooks > New to create a Webhook.

Configure the Webhook

1. Click Edit in the Webhook Settings pane to begin configuring your Webhook.

2. Under Webhook type, select from the following:

• • Single request: sends a single event with each request.
  • Batched request: sends an array of events with each request. Batch requests require you to set a maximum number of events and payload size for your Webhook. 

If the external API accepts batched requests, use that option. The external application will typically publish its expected format for batched requests as well as the limit of records per request.

3. Enter the Webhook URL where you'd like to post data.

4. Under Request headers, enter any required header values such as authorization keys or tokens.

5. Set the Rate limiting parameter for your Webhook. The default is 100 per second.

Be aware of the rate threshold for the external API, and make sure to set Rate limiting within that threshold.

Configure Webhook triggers

Within each channel you use in Cordial, select the events you want to set as triggers for the Webhook under Trigger Events.

You can from choose the following options:

• Send all events: send all events configured in the channel.
• Allowed events: choose specific events to send.
• Blocked events: choose specific events to block.
• Block all events: block all events configured in the channel.

Allowed and blocked events

Choose from the available system and custom event options under Trigger Events to configure allowed and/or blocked events for each trigger.

• Find a full list of our system events, organized by channel, here.

Configure Webhook payload

Configure the payload of your Webhook so it's compatible with the schema expected by the external application API using the setPayload utility. See example below. This enables Cordial to send properly-formatted payloads to any applicable API.

1. Click Edit under Webhook Payload to access and edit the Payload Editor. 

To edit a Webhook that's already enabled, you'll need to disable the Webhook, make the desired changes, then enable it again after making any changes.

2. Configure the payload so it adheres to the format required by the external API.

• You can find a code example here.

If you've configured the Webhook to send batched requests, the payload will be constructed as an array of objects. If you've configured the Webhook to send a single request, the payload will be constructed as a single object.

3. Click Data Variables to access a data dictionary that allows you to reference and/or copy any available variables and paste them into your Payload Editor.

The payload script has access to both the $event object and the $contact object. 

3. At the bottom of the Payload Editor, choose the event and contact ID for your preview.

4. Click Preview to see the properly formatted payload.

Payload code example

One of the main benefits of Cordial's Webhook solution is that you can customize the payload schema to match the schema of the target API. This is accomplished via Smarty scripting using the setPayload utility, which creates either an object or an array of objects depending on if you're sending single or batched requests, respectively: {$utils->setPayload($payload)}

Below is a simple example of how you can transform a Cordial event into a payload that's compatible with the schema of the target API.

• This is an abridged example of a Cordial click event.

  {
        "cID": "63b5f16c7f20a477c00f3fe4",
        "mdtID": "63b5f17f54309c8db87d706e",
        "mcID": "...rm202301042140:63b5f16c7f20a477c00f3fe4:1",
        "first": true,
        "_id": "63b5f3337c57a2826500246c",
        "link": "https://www.acme.com/",
        "a": "click",
        "ats": "2023-01-04T21:44:15+0000",
        "bmID": "45:63b5f17f54309c8db87d706e:rm202301042140"
  }
  

• In this example, the API JSON is structured differently than Cordial's event, with different keys and a properties object.

  {
     "event": "string",
     "properties": {
        "time": "string",
        "event_id": "string",
        "user_id": "string"
     }
  }
  

• Notice how the $payload object is assigned to match the API schema, mapping the API keys to Cordial's event values.

  {$payload.event = $event.a}
  {$payload.properties.time = $event.ats}
  {$payload.properties.event_id = $event._id}
  {$payload.properties.user_id = $event.cID}
  {$utils->setPayload($payload)}
  

• The payload now contains the Cordial event values in the schema of the target API.

  {
     "event": "click",
     "properties": {
        "time": "2023-01-04T21:44:15+0000",
        "event_id": "63b5f3337c57a2826500246c",
        "user_id": "63b5f16c7f20a477c00f3fe4"
     }
  }
  

Test and enable the Webhook

The Cordial UI requires that you test Webhooks before they can be enabled. This ensures that each Webhook functions as intended before it's deployed.

You can use webhook.site or a similar tool to produce test URLs.

1. Select the Test button in the left sidebar to set up a test of your Webhook.

2. In the first dropdown, select either All events or the individual event you'd like to test.

3. In the second dropdown, you can choose the contact or audience to test.

4. Selecting the contact will launch a test version of your Webhook. If your Webhook is successful, you'll see a success message, the Request from Cordial, and the Response from Destination.

4. Enable your successful Webhook in the left sidebar.

Edit enabled Webhook

To edit a Webhook that's already enabled, you'll need to disable the Webhook, make the desired changes, then enable it again.

After you've re-enabled a Webhook, Cordial will queue all events that happened within 24 hours of disablement and send them. 

Remove a Webhook

You can easily remove a Webhook by locating it on the Webhooks page, hovering over the arrow, and selecting Remove.