Introduction

Webhooks allow you to receive event notifications in your own application. By registering a URL to post events to, you are able to monitor and respond to events that occur in the Apostle.io ecosystem.

Currently the Webhooks system contains limited functionality. Only events pertaining to failed delivery requests are posted to registered urls.

Registering A URL

To register a new webhook url, visit the settings area for your domain (click the cog in the main navigation). Webhooks are subscribed to on a per domain basis. In the settings area, select the Webhooks tag, hit ”Add Webhook“ and enter your url. Once added, you can edit, delete and send a test webhook.

Webhook Format

Webhook events are sent in a batched format. Events are aggregated and processed approximately once a minute. A batch will be sent to your subscribed URLs as the JSON body of a post request in the following format.

1
2
3
4
5
{ "domain_id": "your domain id here", "events": [] }

Only two root keys are provided, your domain id (you can see this in the URL when viewing your domain on Apostle.io), and an array of events. Each event follows a standard format:

1
2
3
4
5
6
7
8
{ "id":"f293fb86-775f-48ef-9ea4-16b1fedd416d", "message":"This is a test webhook event", "type":"test", "timestamp":1234567890, "data":{} }

Note: We promise to deliver each event at least one time. Please ensure that your processing of events is idempotent. If you receive an event with the same id as a previous event, you can assume it is the same event and choose to discard it. In practice, you should only see events once, but our durability guarantee is such that we’d rather deliver it twice, than not at all.

Event Types

Currently there are only two types of Event Types being processed. We will be adding more depending on customer demand (email us your requests!), so new events may start arriving at any time.

test

A test event sent from the web UI when setting up your webhook urls. The data value will be an empty object.

1
2
3
4
5
6
7
8
{ "id":"f293fb86-775f-48ef-9ea4-16b1fedd416d", "message":"This is a test webhook event", "type":"test", "timestamp":1234567890, "data":{} }

delivery_request.invalid_template_slug

This event is fired when a request to deliver an email has failed due to an invalid template slug. The slug was either missing, or did not have an associated template. The data value will be an object with a key "slug".

1
2
3
4
5
6
7
8
{ "id":"cdeae957-f4b2-4ec8-99b6-01385a6c2e85", "message":"Failed to send email to ‘mal@apostle.io’; could not find template for slug ‘inv’", "type":"delivery_request.invalid_template_slug", "timestamp":1234567890, "data":{"slug":"inv"} }