Webhooks
Omnivery can make an HTTP POST to your backend URLs whenever tracked events occur with your messages. These calls are called webhooks. The webhooks are set for each individual domain and you can set up to 3 different URLs for different types of events. In addition the webhook callback URL can be set individually in the API call parameters or using SMTP header at the time of send.
Setting up Webhooks
Webhooks are configured per domain and type of event. For each of the event types you can configure up to 3 distinct webhooks in any supported format.
Currently the following webhook formats are supported:
- Bloomreach Engage (
bloomreach) - webhook format for Bloomreach Engage. This format is set as default when using Bloomreach Engage platform and doesn't require manual configuration as Bloomreach sets the webhook URL automatically in its API calls. - Bloomreach Events (
bloomevents) - this format is a special format that passes webhooks as events to Bloomreach Engage platform. This format requires specific type of setup in the Bloomreach platform. Consult our support in case you need to use Bloomreach Events. - Mailgun (`mailgun) - Mailgun compatible webhook format.
- Sendgrid (
sendgrid) - Sendgrid compatible webhook format. - Bird/SparkPost (
sparkpost) - Bird/SparkPost compatible webhook format.
Additionally you can pass a webhook endpoint URL and format in the API call or using SMTP headers (X-OV-Callback-URL and X-OV-Callback-Format) to override the domain webhook settings.
Webhook process
The following diagram shows the process from the message submission to our SMTP or API endpoint, delivery to mailbox and how the events are relayed to webhooks.
Webhook events are generated for every single action that occurs on the message level - delivery, bounce as well as recipient actions - opens, clicks, unsubscribes, complaints depending on which trackings are enabled.
Speed is one of the major advantages of webhooks. As the webhooks are called when events occur the information is transmitted almost instantly and there is very little delay between the event and webhook call. The speed of processing also means the calls are asynchronous - meaning events may be trasmitted out of order - eg. open before delivery, etc. For this reason it's very important to use the timestamps provided in the event data rather then time of receiving the data.
How we handle webhook endpoint responses
Webhook calls expect to receive a 2xx HTTP status status code in a response to a succesfully processed webhook call. Responses with different status code will be retried at a later time if we believe this status may be temporary, discarded or in some cases may result in webhook endpoint being disabled.
Following table provides information on how individual responses will be handled:
| HTTP response code | Action |
|---|---|
| 2xx | none - The webhook call has been succesfully delivered to the endpoint. |
| 3xx | Disable - any and all redirects will result in webhook endpoint being disabled for security purposes. |
| 400 Bad Request | Discard - no further attemps for deliver this event to the webhook endpoint will be performed |
| 401 Unauthorized | Disable - webhook endpoint will be disabled |
| 402 Payment Required | Disable - webhook endpoint will be disabled |
| 403 Forbidden | Disable - webhook endpoint will be disabled |
| 404 Not Found | Disable - webhook endpoint will be disabled |
| 405 Method Not Allowed | Disable - webhook endpoint will be disabled |
| 406 Not Acceptable | Discard - no further attemps for deliver this event to the webhook endpoint will be performed |
| 407 Proxy Authentication Required | Disable - webhook endpoint will be disabled |
| 408 Request Timeout | Defer - retry call at a later time |
| 409 Conflict | Defer - retry call at a later time |
| 410 Gone | Defer - retry call at a later time |
| 411 Length Required | Discard - no further attemps for deliver this event to the webhook endpoint will be performed |
| 412 Precondition Failed | Defer - retry call at a later time |
| 413 Payload Too Large | Discard - no further attemps for deliver this event to the webhook endpoint will be performed |
| 414 URI Too Long | Discard - no further attemps for deliver this event to the webhook endpoint will be performed |
| 415 Unsupported Media Type | Discard - no further attemps for deliver this event to the webhook endpoint will be performed |
| 416 Range Not Satisfiable | Discard - no further attemps for deliver this event to the webhook endpoint will be performed |
| 417 Expectation Failed | Discard - no further attemps for deliver this event to the webhook endpoint will be performed |
| 418 I'm a teapot (RFC 2324, RFC 7168) | Defer - retry call at a later time |
| 421 Misdirected Request | Defer - retry call at a later time |
| 422 Unprocessable Content | Discard - no further attemps for deliver this event to the webhook endpoint will be performed |
| 423 Locked (WebDAV; RFC 4918) | Disable - webhook endpoint will be disabled |
| 424 Failed Dependency (WebDAV; RFC 4918) | Defer - retry call at a later time |
| 425 Too Early (RFC 8470) | Defer - retry call at a later time |
| 426 Upgrade Required | Defer - retry call at a later time |
| 428 Precondition Required (RFC 6585) | Defer - retry call at a later time |
| 429 Too Many Requests (RFC 6585) | Defer - retry call at a later time |
| 431 Request Header Fields Too Large (RFC 6585) | Discard - no further attemps for deliver this event to the webhook endpoint will be performed |
| 451 Unavailable For Legal Reasons (RFC 7725) | Disable - webhook endpoint will be disabled |
| 5xx | Defer - all server errors will result in webhook calls being retried at a later time. |
DEFER - When the webhook call is being deferred based on the response status code, it will be retried at following intervals - 1 minute, 5 minutes, 10 minutes, 15 minutes, 30 minutes, 1 hour, 2 hours, 4 hours and 8hours and 8 hours adding up to 24 hours of total retry period.
DISABLE - certain response statuses indicate that the endpoint is no longer available and warrant disabling the endpoint altogether. This will prevent any new events from being queued for this webhook endpoint but any events already queued will still be attempted. The disable action can only affect webhooks set in the domain settings and will not affect if the webhook URL is provided directly during message submission.
DISCARD - response status codes indicating an issue with the content of the call will trigger the event being discarded. Since the content is given and won't change during subsequent calls it makes no sense to retry delivering the data at a later point in time.
When implementing your respective webhook endpoints always make sure that the responses you return are following the above listed logic. This will help you avoid situations where endpoints would be disabled for the wrong reason or calls not being retried and discarded.
Omnivery supports webhook calls in various formats. Please consult the documentation for the specific API you are using for details of the webhook format.