Webhook Integration

Webhooks are user-defined HTTP callbacks. When a supported event occurs, Digital Onboarding's servers will connect to an HTTP endpoint of your choosing to provide you with near real-time information about your customers. This may be a CRM system, your own servers, or any other endpoint which can then update your systems and keep them updated in real-time.

Overview

Digital Onboarding servers will send events to your endpoint, as configured under Settings, API Access, under the Webhook panel. These events will be in the form of an HTTP POST, and will be sent in real-time upon any of the webhook actions occurring.

The shape of the HTTP POST takes this form:

POST https://www.yourserver.com/your/endpoint/

The message payload is sent using application/json and takes the general form:

{
  "contact_id": "1058c359-4ffd-4039-b474-ff552b33474b",
  "type": "contact.updated"
  ...
}

Which contains these fields:

field	description
contact_id	The unique identifier for the affected contact.
type	The webhook event being reported. See below for a list of event types.

If you are familiar with HTTP Archive format, the entire exchange in HAR looks like this (note the x-signature header):

View HAR Capture

{
  "log": {
    "version": "1.2",
    "creator": { "name": "Webhook.site", "version": "1.0" },
    "entries": [
      {
        "startedDateTime": "2021-06-23 00:11:57",
        "request": {
          "method": "POST",
          "url": "https://webhook.site/7b6202b5-16a4-45bf-9502-59b6b44de2d9",
          "headers": [
            { "name": "connection", "value": "close" },
            { "name": "content-length", "value": "78" },
            { "name": "content-type", "value": "application/octet-stream" },
            { "name": "user-agent", "value": "hackney/1.17.4" },
            { "name": "host", "value": "webhook.site" },
            {
              "name": "x-signature",
              "value": "t=1624407116,s0=81F7C67B7A20120F35D4F0DEECC15000E570E00E24E18A4A114B11939B5E6C23,s1=8AD51BD0F21E48F70A9A05D38B43CFF1B9A561DD5CDCEA8748E23D738A98824B"
            }
          ],
          "bodySize": 78,
          "postData": {
            "mimeType": "application/json",
            "text": "{\"contact_id\":\"1058c359-4ffd-4039-b474-ff552b33474b\",\"type\":\"contact.updated\"}"
          }
        },
        "response": {
          "status": 200,
          "httpVersion": "HTTP/1.1",
          "headers": [{ "name": "Content-Type", "value": "text/plain" }],
          "content": { "size": 0, "text": "", "mimeType": "text/plain" }
        }
      }
    ]
  }
}

Additional Notes

• If an HTTP 4xx response code is returned by your server, the webhook will be retried up to 12 times over approximately 2 hours at a decreasing frequency until a 2xx response status is obtained.
• If an HTTP 5xx response code is returned by your server, no retries will be attempted.
• There are no requirements for what is returned in the response body.

Security & Authentication

Webhooks contain an x-signature HTTP header which can be used to verify the authenticity of the incoming webhook. More information about API key usage can be found on the API Access section of the API documentation.

The x-signature header contains the following fields:

field	description
t	The server timestamp, used to compute the HMAC authenticity. This is a unix timestamp.
s0	The signature using your first API credential. This will always be present.
s1	The signature using your second API credential. This is not present if you only have one credential.

API credentials are configured within the Settings > API Access > Credentials area on the Digital Onboarding website. You may have a maximum of two credentials active at any given time.

These credentials will be utilized to generate signatures which will be passed via the s0 and s1 values in the x-signature header. Note also that the server timestamp value is passed as t.

For the above example JSON payload, you can validate the provided signature using an HMAC Generator / Tester Tool:

(screenshot courtesy of HMAC Generator / Tester Tool)

Note in the above example that the returned Computed HMAC matches the s0 value also provided above. You may need to force uppercase depending on your server's programming language or locale settings. Digital Onboarding will always send signatures in all-caps. Above screenshot for computational demonstration only.

You will generate an HMAC signature with these inputs:

field	description
Secret Key	Your API Key from your Digital Onboarding Settings > API Access > Credentials
Message	The provided t timestamp value and the provided JSON payload, separated by a . period

Events

Event Types

Digital Onboarding will send webhooks for the following event types:

type	description
contact.created	Sent when a new contact has been entered into the system
contact.updated	Sent when contact's personal information (excluding opt-in/opt-out status) has changed
contact.unsubscribed	Sent when contact has unsubscribed from communications
cta.clicked	Sent when contact has clicked on a call to action within a campaign
enrollment.accepted	Sent when contact has accepted an enrollment form
enrollment.declined	Sent when contact has declined an enrollment form
objective.completed	Sent when contact has completed an objective
reward.earned	Sent when contact has earned a reward

Each type of webhook contains a different payload described below.

All UUID field values are generated by Digital Onboarding according to RFC 4122.

contact.created

{
  "contact_id": "8b008018-cb47-427c-9a9e-a5796bc93428",
  "type": "contact.created"
}

field	type	description
contact_id	UUID	A unique id for the contact
type	String	The notification webhook type, i.e. contact.created

contact.updated

{
  "contact_id": "8b008018-cb47-427c-9a9e-a5796bc93428",
  "type": "contact.updated"
}

field	type	description
contact_id	UUID	A unique id for the contact
type	String	The notification webhook type, i.e. contact.updated

contact.unsubscribed

{
  "channel": "email",
  "contact_id": "8b008018-cb47-427c-9a9e-a5796bc93428",
  "type": "contact.unsubscribed"
}

field	type	description
channel	String	The channel the contact unsubscribed from email|sms
contact_id	UUID	A unique id for the contact
type	String	The notification webhook type, i.e. contact.created

cta.clicked

{
  "content_block_id": "7031e819-00ac-4eb1-89ff-6c6d1bf5452d",
  "journey_id": "8b008018-cb47-427c-9a9e-a5796bc93428",
  "type": "cta.clicked"
}

field	type	description
content_block_id	UUID	A unique id for the content block that was clicked
journey_id	UUID	A unique id for the journey
type	String	The notification webhook type, i.e. cta.clicked

enrollment.accepted

{
  "contact_id": "9d3a021e-27c7-4e1a-827e-97528992611e",
  "id": "a4a5a058-a80a-4278-848d-bb47b53ec20e",
  "journey_id": "eb4645b2-9e73-4c75-8af3-26f86c401d8a",
  "name": "My Enrollment Widget",
  "objective_id": "44def651-51dd-4809-9988-f8c848bb059a",
  "source": "system",
  "team_id": "f3bddffd-598f-4868-b1e0-9f05681a4688",
  "type": "enrollment.accepted"
}

field	type	description
contact_id	UUID	A unique id for the contact
id	UUID	A unique id for the content block that was accepted
journey_id	UUID	A unique id for the journey
name	String	The user-provided name of the enrollment widget used for insights and analytics
objective_id	UUID	An objective id for the objective that was completed by the contact
source	String	The source the that triggered the action, e.g. "system"
team_id	UUID	A unique id for the team
type	String	The notification webhook type, i.e. enrollment.accepted

enrollment.declined

{
  "contact_id": "9d3a021e-27c7-4e1a-827e-97528992611e",
  "id": "a4a5a058-a80a-4278-848d-bb47b53ec20e",
  "journey_id": "eb4645b2-9e73-4c75-8af3-26f86c401d8a",
  "name": "My Enrollment Widget",
  "objective_id": "44def651-51dd-4809-9988-f8c848bb059a",
  "source": "system",
  "team_id": "f3bddffd-598f-4868-b1e0-9f05681a4688",
  "type": "enrollment.declined"
}

field	type	description
contact_id	UUID	A unique id for the contact
id	UUID	A unique id for the content block that was accepted
journey_id	UUID	A unique id for the journey
name	String	The user-provided name of the enrollment widget used for insights and analytics
objective_id	UUID	An objective id for the objective that was completed by the contact
source	String	The source the that triggered the action, e.g. "system"
team_id	UUID	A unique id for the team
type	String	The notification webhook type, i.e. enrollment.declined

objective.completed

{
  "contact_id": "9d3a021e-27c7-4e1a-827e-97528992611e",
  "journey_id": "2fc4ad26-8c89-4998-a838-5a75af3c735c",
  "objective_id": "44def651-51dd-4809-9988-f8c848bb059a",
  "type": "objective.completed"
}

field	type	description
contact_id	UUID	A unique id for the contact
journey_id	UUID	A unique id for the journey
objective_id	UUID	An objective id for the objective that was completed by the contact
type	String	The notification webhook type, i.e. objective.completed

reward.earned

{
  "action_id": "cf25d2ae-5e31-11ee-8c99-0242ac120004",
  "contact_id": "c811b212-5e31-11ee-8c99-0242ac120002",
  "id": "cf25d164-5e31-11ee-8c99-0242ac120002",
  "journey_id": "cf25d2ae-5e31-11ee-8c99-0242ac120002",
  "reward_set_id": "cf25d3e4-5e31-11ee-8c99-0242ac120002",
  "template_id": "cf25d2ae-5e31-11ee-8c99-0242ac120003",
  "type": "reward.earned"
}

field	type	description
action_id	UUID	A unique id for the reference action
contact_id	UUID	A unique id for the contact
id	UUID	A unique id for the action
journey_id	UUID	A unique id for the journey
reward_set_id	UUID	A reward set id for the reward earned
template_id	UUID	A template id for the action
type	String	The notification webhook type

survey.completed

{
  "contact_id": "9d3a021e-27c7-4e1a-827e-97528992611e",
  "id": "a4a5a058-a80a-4278-848d-bb47b53ec20e",
  "journey_id": "eb4645b2-9e73-4c75-8af3-26f86c401d8a",
  "name": "My Survey Widget",
  "objective_id": "44def651-51dd-4809-9988-f8c848bb059a",
  "source": "system",
  "team_id": "f3bddffd-598f-4868-b1e0-9f05681a4688",
  "type": "survey.completed"
}

field	type	description
contact_id	UUID	A unique id for the contact
id	UUID	A unique id for the content block that was accepted
journey_id	UUID	A unique id for the journey
name	String	The user-provided name of the survey widget, used for insights and analytics
objective_id	UUID	An objective id for the objective that was completed by the contact
source	String	The source the that triggered the action, e.g. "system"
team_id	UUID	A unique id for the team
type	String	The notification webhook type, i.e. survey.completed

Testing

The Digital Onboarding platform contains a feature that allows you to test your webhook configuration by sending sample requests to you server.

Visit Settings > API Access > Webhooks and click on "Test" to send sample requests to your server.