Receive delivery feedback webhooks¶

This guide will explain the basics of receiving delivery & bounce status updates via webhooks from Marigold Engage Delivery Cloud.

How to set up webhooks:

1. Subscribe to delivery events
2. Receive delivery events

Webhook concept¶

A webhook is a way to receive update events being pushed instead of polling continuously for updates.

A webhook (also called a web callback or HTTP push API) is a method to provide external applications with real-time information about data changes in a platform. A webhook delivers data to the external applications at the moment that there is a change, resulting in data being pushed immediately. Unlike REST APIs where the external application would need to poll the API at a regular interval in order to get the changed data. This makes webhooks much more efficient for both provider and consumer.

The webhook engine will do an HTTP POST request to an endpoint at the customer system, respecting retry and exponential backoff policies. The webhooks will try to resend the webhook data if the request towards the customer system fails, using a retry schedule and retry policy.

Retry policy¶

• Maximum number of attempts – The Webhook engine will try to deliver the event maximum 5 times, respecting exponential increased delayed intervals, starting with a 1 second delay.
• Event time-to-live (TTL) – The webhook engine will try to deliver the message within a time-range of 24h, messages older than 24h are considered outdated and will be removed

Retry schedule¶

When the Webhook engine is unable to deliver the event, the Webhook engine decides whether it should retry the delivery or move the event to dead letters based on the type of the error. When one of the errors occurs, the Webhook engine will retry at a delayed interval.

• Error codes that trigger a retry: 429 Too Many Requests, 5xx responses
• Error codes that skip a retry: 400 Bad Request, 413 Request Entity Too Large, 403 Forbidden, 404 Not Found, 401 Unauthorized
• Generic Exceptions: Timeouts, Internal Server Issues

Dead Letters¶

Undeliverable events get stored in dead letters for up to 2 weeks. We provide an API to fetch metadata about these dead letters which include the total number of retries, the final HTTP response and code, etc.. The API also allows for rescheduling these dead letters or fetching and deleting the entire event by id.

CloudEvents format¶

All Marigold Engage Webhook events are delivered using the CloudEvents format.

1. Subscribe to delivery events¶

The concept of webhook allows subscribing to a range of events of various types, instead of polling for updates. A webhook will push the event data to an external application using an HTTP request.

So to subscribe to delivery events, the following information is needed:

1. A webhook URL to receive events from EDC. This is an application on your end that is capable of receiving the pushed events.
2. Choose the type of events you want the application to notify you about.

See documentation on managing webhook subscriptions in the webhook subscriptions developer documentation.

It is possible to subscribe to multiple event types or specific event types.

The most notable event types are:

• com.sdc.deliveries.email.sent: An event that is triggered when the email message is sent towards the ISP and EDC has gotten an success ISP response back.
• com.sdc.deliveries.email.failed: An event that is triggered when the email message is sent towards the ISP and EDC has gotten an undeliverable ISP response back.

2. Receive delivery events¶

In the above steps, we explained how to manage webhook subscriptions. Now, we will show how to receive the delivery events.

We want to receive the delivery events, each time an email messages was sent to the ISP.

By using the Marigold Engage Delivery Cloud API or via Marigold Engage to send messages, we can trigger the delivery events. In the "send email messages" guide, we explain more in detail how to use to send messages via the API.

Each time the "/messages/send" API is called, Marigold Engage will send an HTTP POST request to the webhook endpoint.

POST /email/v1/messages/send

will result in a delivery event being pushed to the webhook endpoint:

POST https://yourcompany.abc/endpoint

with a JSON request body that contains the following fields:

{
  "id": "1516952e520547049b8897b24e44553e",
  "tenant": "EU.YOURCOMPANY",
  "source": "/sdc/mailer",
  "type": "com.sdc.deliveries.email.sent",
  "time": "2022-03-16T12:56:04.8111884Z",
  "specversion": "1.0",
  "dataschema": "#/v1",
  "datacontenttype": "application/json",
  "subject": "674d25d7319b4549a88cefdda049989e_92233793802426",
  "data": {
    "result": "success",
    "context": {
      "profile": "crm-id-123456789",
      "tags": ["resto-order-now-campaign-spring"],
      "metadata": "{\"name\":\"jane.doe\",\"ref\":123456789}"
    },
    "outcome": "250 Ok",
    "recipient": "jane.doe@example.com",
    "external_reference": "674d25d7319b4549a88cefdda049989e_92233793802426",
    "timestamp": "2022-03-16T12:56:00.1260605"
  }
}

The breakdown of the delivery event fields is as follows:

• event wrapper: the event metadata fields, that wrap the event data and provide some context about the event.
• event data: the actual event payload related to the delivery status of a message.

Event metadata wrapper¶

{
  "id": "1516952e520547049b8897b24e44553e",
  "tenant": "EU.YOURCOMPANY",
  "source": "/sdc/mailer",
  "type": "com.sdc.deliveries.email.sent",
  "time": "2022-03-16T12:56:04.8111884Z",
  "specversion": "1.0",
  "dataschema": "#/v1",
  "datacontenttype": "application/json",
  "subject": "674d25d7319b4549a88cefdda049989e_92233793802426"
}

These fields represent the metadata of the event, with an ID, the source, the type, the time, the specification version, the data schema and the data content type. Review the webhook API reference for more details about the event metadata fields.

Event data¶

{
  "data": {
    "result": "success",
    "context": {
      "profile": "crm-id-123456789",
      "tags": ["resto-order-now-campaign-spring"],
      "metadata": "{\"name\":\"jane.doe\",\"ref\":123456789}"
    },
    "outcome": "250 Ok",
    "recipient": "jane.doe@example.com",
    "external_reference": "674d25d7319b4549a88cefdda049989e_92233793802426",
    "timestamp": "2022-03-16T12:56:00.1260605"
  }
}

The event data contains the actual event payload with a number of related deliverability fields and several message-related metadata.

The fields: context, recipient and external_reference refer to the recipient and passed & message metadata tags. The fields: result, outcome and timestamp are technical deliverability fields.

Review the webhook API reference for more details about the event data fields.

Each time a message is sent, Marigold Engage will send a similar webhook request to the webhook endpoint. This would allow you to track the delivery status of each stage.

Event data from Marigold Engage¶

Messages being sent via Engageor Campaign will use Marigold Engage Delivery Cloud as delivery engine. All the message context information will automatically be provided by SMC/Campaign and passed along EDC.

The delivery events triggered by an Engage campaign, will have some specific data in the context part of the event.

{
  "id": "1516952e520547049b8897b24e44553e",
  "tenant": "EU.YOURCOMPANY",
  "source": "/sdc/mailer",
  "type": "com.sdc.deliveries.email.sent",
  "time": "2022-03-16T12:56:04.8111884Z",
  "specversion": "1.0",
  "dataschema": "#/v1",
  "datacontenttype": "application/json",
  "subject": "674d25d7319b4549a88cefdda049989e_92233793802426",
  "data": {
    "result": "success",
    "context": {
      "metadata": "{\"mid\":\"6025\",\"cid\":\"0\",\"lid\":\"9981\",\"aiq\":\"92233829321154\",\"uid\":\"123\",\"aid\":\"0\"}",
      "profile": "9981.123",
      "tags": ["CPG_1_1357", "CPG_EU.ACME_6025"]
    },
    "outcome": "250 Ok",
    "recipient": "jane.doe@example.com",
    "external_reference": "674d25d7319b4549a88cefdda049989e_92233793802426",
    "timestamp": "2022-03-16T12:56:00.1260605"
  }
}