The Outkit Support and Developer Hub

Welcome to the Outkit support and developer hub. Here you'll find comprehensive guides and documentation to help you start working with Outkit as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started     Guides

Webhooks

Get programmatically notified when something happens to a message.

Webhooks make it possible to be automatically notified (over HTTPS) when something happens to a message. They can be very useful if you have advanced needs or want to set up a deep integration with Outkit, but are not required for most accounts.

Use cases

Here are some typical use cases for webhooks:

  • Submit messages to Outkit for rendering, but deliver them yourself when we are done rendering
  • Show a custom/in-house live feed of messages that you have submitted to Outkit
  • Take action if a message fails to be delivered to the backend

... or something else entirely. That’s the beauty of webhoooks - if you know what you’re doing you can use them to create basically anything.

Detailed description

Our webhooks work very similary to other webhooks you may have interacted with. Here’s a quick rundown:

  • We always use the POST verb
  • The content-type is application/json
  • Your endpoint must return a 2xx HTTP status code to acknowledge that you have received the notification

The body of the POSTed request adheres to the following JSON structure:

{
  "id": "<id-of-webhook-notification-event>",
  "webhook_id": "<id-of-webhook-definition>",
  "event": "message.submitted",
  "object_type": "message",
  "object_id": "<id-of-message>",
  "data": {
    // This is a complete message object, including 
    // the changes that triggered the webhook
    "type": "email",
    "subject": "Welcome to AcmeCorp!",
    ...
  },
}

You may currently encounter the following events:

  • message.submitted
  • message.rendered
  • message.delivered
  • message.failed
  • message.done

Note that message.done will be triggered independently and in addition to the event that marked the message as done, for example message.delivered or message.failed.

We do not guarantee the ordering of these events. They are triggered in the correct order within our system, but due to queueing and network conditions, you may sometimes receive them out of order.

We retry delivery roughly once per hour until your endpoint returns a 2xx HTTP status code. Note that a 3xx redirect will be counted as a failure, and trigger our retry logic.

Delivery is retried for a maximum of 72 times (so roughly for three days), at which point we give up. There is currently no notification set up to alert you of this, but we expect to offer this in the future.

All webhook notifications are queued, and while do our best to keep delays to a minimum, you may sometimes experience significant delay before receiving your notification.