Setting up Dyspatch Webhooks

Setting up Dyspatch webhooks allow you to POST data to a specified URL every time an email template action occurs. Follow along on how to get started.

How to Setup a Webhook Relay

Once you have a URL to which you would like to forward webhook events, navigate to the Apps & Integrations page. Select Add Integration.

Select the Workflow integration option.

Under "Choose an Integration", select Webhook. Add in your Webhook URL and a short description. Once completed, click the Add Integration button.

That's it! Any time you or your team performs an action on an email template, Dyspatch will relay a webhook event to your Webhook URL.

Webhook Events

• comment_created - Triggered when a comment is created or replied to in the email builder.
• template_submitted - Triggered when an email is submitted for approval.
• template_approved - Triggered when an email draft has been approved.
• template_rejected - Triggered when an email draft has been rejected.
• template_unpublished - Triggered when an email draft has been rolled back to a previous draft. This webhook has the information for the draft that was rolled back.
• template_republished - Triggered when an email has been rolled back to a previous draft. This webhook has the information for the draft getting published.
• template_locked_for_translation - Triggered when a draft is locked for translation.
• template_unlocked_for_translation - Triggered when a draft is locked for translation.

Sample Webhook

Dyspatch webhooks are all generally same shape. The parts of the webhook include:

• comment - Optional. Contains any HTML styled comment that may have been submitted with the event.
• draft - Metadata about the draft.
  • createdAt - Draft creation timestamp (UTC).
  • id - Draft ID.
  • name - Draft name.
  • updatedAt - Draft last updated timestamp (UTC).
  • url - Link to the draft in Dyspatch.
• event - Draft event. See supported events in Webhook Events
• template - Metadata about the template.
  • createdAt - Template creation timestamp (UTC).
  • description - Template description.
  • folder - Name of the folder the template is located in.
  • id - Template ID.
  • name - Template name.
  • updatedAt - Template last updated timestamp (UTC).
• text - Additional text describing the event.
• user - Metadata about the user triggering the event.
  • email - User's email.
  • firstName - User's first name.
  • lastName - User's last name.

Here is a sample webhook for the comment_created event.

{
  "comment": "<p style=\"margin-top:0;margin-bottom:0\">This is a comment left on a template</p>",
  "draft": {
    "createdAt": "2022-11-30T18:45:11.008906Z",
    "id": "tdft_01gk4xptq0730pc8gsabcd1234",
    "name": "First draft",
    "updatedAt": "2022-12-01T16:16:59.304386Z"
  },
  "event": "comment_created",
  "template": {
    "createdAt": "2022-11-30T18:45:11.00703Z",
    "description": "Template description sample text",
    "folder": "Test Workspace",
    "id": "tdft_01gk4xptq0730pc8gsabcd1234",
    "name": "Test template name",
    "updatedAt": "2022-12-01T16:16:59.308662Z"
  },
  "text": "Comment added to template \"Test template name\": \"This is a comment left on a template\"",
  "user": {
    "email": "alfred@dyspatch.io",
    "firstName": "Alfred",
    "lastName": "Pennyworth"
  }
}

Notice that the locked_for_translation event webhook below doesn't include the comment field:

{
  "draft": {
    "createdAt": "2022-11-30T18:45:11.008906Z",
    "id": "tdft_01gk4xptq0730pc8gsabcd1234",
    "name": "First draft",
    "updatedAt": "2022-12-01T16:16:59.304386Z"
  },
  "event": "template_locked_for_translation",
  "template": {
    "createdAt": "2022-11-30T18:45:11.00703Z",
    "description": "Template description sample text",
    "folder": "Test Workspace",
    "id": "tdft_01gk4xptq0730pc8gsabcd1234",
    "name": "Test template name",
    "updatedAt": "2022-12-01T16:16:59.308662Z"
  },
  "text": "Draft \"First Draft\" (\"Test template name\") was unlocked for translation by Alfred Pennyworth",
  "user": {
    "email": "alfred@dyspatch.io",
    "firstName": "Alfred",
    "lastName": "Pennyworth"
  }
}

Verify Webhooks Events

You can verify a webhook is coming from Dyspatch by calculating the digital signature. Dyspatch signs each webhook request event with a X-Signature header which is generated with a secret key and the corresponding JSON payload.

Retrieve Your Endpoint's Secret

You can find your endpoint's secret by navigating to the Admin dashboard, and selecting the Apps & Integrations tab. From here, scroll to the Workflows section and click on the actions downdrop menu () on the Webhook integration, and select Edit Details. A modal will pop up with your signing secret. Click the Reveal option to display your secret.

Verify the Signature

Once you have your signing secret, you can compute the HMAC hash (signing secret and JSON payload) and compare it to the X-Signature header value from the request. If they are equal, this is a valid request coming from Dyspatch.