Webhooks

Webhooks allow us to push raw events we collect about your emails over to your servers. Batches of events are delivered through a POST request to the defined target URL. You can use this endpoint to create and manage webhooks, or you can create one from the app (EU). For inbound relay webhooks, see Relay Webhooks.

Batch Information

Any webhook batch that does not receive an HTTP 200 response will be retried for a total of 8 hours before the data is discarded.
Each webhook batch contains the header X-MessageSystems-Batch-ID, which is useful for detecting and prevention of processing duplicate batches. Additionally within each event the event_id is unique and can also be used in duplicate detection and prevention.
Webhooks posting to your endpoint will timeout after 10 seconds. For best results, write webhook batches to disk and then process asynchronously to minimize data loss if you have a problem with your database.
Webhook batch status is available for 24 hours via the UI or the API.
See Best Practices for Managing Webhook Data Streams for more information on how best to consume webhooks.
See Webhook Authentication and Security for highly recommended security measures.
For further information on our event types see the Webhook Event Reference Guide

Webhook Event Types

You can receive any of the following types of events in webhook payloads.

bounce Event

Remote MTA has permanently rejected a message.

{
  "msys": {
    "message_event": {
      "amp_enabled": true,
      "bounce_class": "1",
      "campaign_id": "Example Campaign Name",
      "click_tracking": true,
      "customer_id": "1",
      "delv_method": "esmtp",
      "device_token": "45c19189783f867973f6e6a5cca60061ffe4fa77c547150563a1192fa9847f8a",
      "error_code": "554",
      "event_id": "92356927693813856",
      "friendly_from": "sender@example.com",
      "initial_pixel": true,
      "injection_time": "2016-04-18T14:25:07.000Z",
      "ip_address": "18.236.253.72",
      "ip_pool": "example-ip-pool",
      "mailbox_provider": "Gsuite",
      "mailbox_provider_region": "Europe - UK",
      "message_id": "000443ee14578172be22",
      "msg_from": "sender@example.com",
      "msg_size": "1337",
      "num_retries": "2",
      "open_tracking": true,
      "rcpt_meta": {
        "customKey": "customValue"
      },
      "rcpt_tags": [
        "male",
        "US"
      ],
      "rcpt_to": "recipient@example.com",
      "rcpt_hash": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
      "raw_rcpt_to": "recipient@example.com",
      "rcpt_type": "cc",
      "raw_reason": "MAIL REFUSED - IP (17.99.99.99) is in black list",
      "reason": "MAIL REFUSED - IP (a.b.c.d) is in black list",
      "recipient_domain": "example.com",
      "recv_method": "esmtp",
      "routing_domain": "example.com",
      "scheduled_time": "1588348800",
      "sending_ip": "18.236.253.72",
      "sms_coding": "ASCII",
      "sms_dst": "7876712656",
      "sms_dst_npi": "E164",
      "sms_dst_ton": "International",
      "sms_src": "1234",
      "sms_src_npi": "E164",
      "sms_src_ton": "Unknown",
      "subaccount_id": "101",
      "subject": "Summer deals are here!",
      "template_id": "templ-1234",
      "template_version": "1",
      "timestamp": "1460989507",
      "transactional": "1",
      "transmission_id": "65832150921904138",
      "type": "bounce"
    }
  }
}

Events

amp_enabled

Indicates whether or not amp format was enabled.

bounce_class

Classification code for a given message (see Bounce Classification Codes).

campaign_id

Campaign of which this message was a part.

click_tracking

Indicates whether or not click tracking was enabled.

customer_id

SparkPost-customer identifier through which this message was sent.

delv_method

Protocol by which SparkPost delivered this message.

device_token

Token of the device / application targeted by this PUSH notification message. Applies only when delv_method is gcm or apn.

error_code

Error code by which the remote server described a failed delivery attempt.

event_id

Unique event identifier.

friendly_from

Friendly sender or 'From' header in the original email.

initial_pixel

Indicates whether or not initial open pixel tracking was enabled.

injection_time

Time at which this message was injected into SparkPost.

ip_address

IP address of the host to which SparkPost delivered this message; in engagement events, the IP address of the host where the HTTP request originated.

ip_pool

IP pool through which this message was sent.

mailbox_provider

Mailbox Provider of the recipient.

mailbox_provider_region

Region of the Mailbox Provider.

message_id

SparkPost-cluster-wide unique identifier for this message.

msg_from

Sender address used on this message's SMTP envelope.

msg_size

Message's size in bytes.

num_retries

Number of failed attempts before this message was successfully delivered; when the first attempt succeeds, zero.

open_tracking

Indicates whether or not open tracking was enabled.

rcpt_meta

Metadata describing the message recipient.

rcpt_tags

Tags applied to the message which generated this event.

rcpt_to

Lowercase version of recipient address used on this message's SMTP envelope.

rcpt_hash

Hashed version of recipient address used on this message's SMTP envelope.

raw_rcpt_to

Actual recipient address used on this message's SMTP envelope.

rcpt_type

Indicates that a recipient address appeared in the Cc or Bcc header or the archive JSON array.

raw_reason

Unmodified, exact response returned by the remote server due to a failed delivery attempt.

reason

Canonicalized text of the response returned by the remote server due to a failed delivery attempt.

recipient_domain

Domain part of the recipient address used on this message's SMTP envelope.

recv_method

Protocol by which SparkPost received this message.

routing_domain

Domain receiving this message.

scheduled_time

Time at which the email was scheduled to be sent.

sending_ip

IP address through which this message was sent.

sms_coding

Data encoding used in the SMS message.

sms_dst

SMS destination address.

sms_dst_npi

Destination numbering plan identification.

sms_dst_ton

Type of number for the destination address.

sms_src

SMS source address.

sms_src_npi

Source numbering plan identification.

sms_src_ton

Type of number for the source address.

subaccount_id

Unique subaccount identifier.

subject

Subject line from the email header.

template_id

Slug of the template used to construct this message.

template_version

Version of the template used to construct this message.

timestamp

Event date and time, in Unix timestamp format (integer seconds since 00:00:00 GMT 1970-01-01).

transactional

Indicates if the transmission was marked as transactional.

transmission_id

Transmission which originated this message.

type

Type of event this record describes.

Webhooks Object

Example

{
  "name": "Example webhook",
  "target": "http://client.example.com/example-webhook",
  "events": [
    "delivery",
    "injection",
    "open",
    "click"
  ],
  "active": true,
  "exception_subaccounts": [
    123
  ],
  "custom_headers": {
    "x-api-key": "abcd"
  },
  "auth_type": "basic",
  "auth_credentials": {
    "username": "basicauthuser",
    "password": "mypassword"
  }
}

Attributes

name string

Name for webhook

target string

URL of the target to which to POST event batches.

events array

Array of event types this webhook will send. Use the Events Documentation endpoint to list the available event types.

active boolean

The status of the webhook. When false, the target will no longer receive batches.

custom_headers object

Object of custom headers to be used during POST requests to target.

exception_subaccounts array

Array of subaccount numbers to prevent receiving events in your webhook (only available for webhooks with Primary and All Subaccounts event source).

auth_type enum

Type of authentication to be used during POST requests to target. Read more about webhook authentication.

Possible Values: none, basic, oauth2

auth_request_details object

Object containing details needed to request authorization token for OAuth 2.0. This is required when auth_type is oauth2.

auth_credentials object

Object containing credentials needed to make authorized POST requests for Basic Authentication. This is required when auth_type is basic. When auth_type is oauth2, it is generated from auth_request_details.

auth_token string

Deprecated in favor of the auth_type field.
Authentication token to present in the X-MessageSystems-Webhook-Token header of POST requests to target.

The SparkPost Webhooks API uses MaxMind software MaxMind License

Request

POST /api/v1/webhooks

{
  "name": "Example webhook",
  "target": "http://client.example.com/example-webhook",
  "custom_headers": {
    "x-api-key": "abcd"
  },
  "auth_type": "oauth2",
  "auth_request_details": {
    "url": "http://client.example.com/tokens",
    "body": {
      "client_id": "CLIENT123",
      "client_secret": "9sdfj791d2bsbf",
      "grant_type": "client_credentials"
    }
  },
  "exception_subaccounts": [
    123
  ],
  "events": [
    "delivery",
    "injection",
    "open",
    "click"
  ]
}

Response

{
  "results": {
    "id": "12affc24-f183-11e3-9234-3c15c2c818c2",
    "links": [
      {
        "href": "/api/v1/webhooks/12affc24-f183-11e3-9234-3c15c2c818c2",
        "rel": "urn.msys.webhooks.webhook",
        "method": [
          "GET",
          "PUT"
        ]
      }
    ]
  }
}

{
  "errors": [
    {
      "code": 400,
      "message": "POST to webhook tokens URL failed",
      "response": {
        "body": "response body",
        "headers": {
          "connection": "close",
          "content-length": "536",
          "content-type": "text/html; charset=iso-8859-1"
        },
        "status": 502
      }
    }
  ]
}

Create a Webhook

POST/api/v1/webhooks

When a webhook is created, a test POST request is sent to the target URL. If this request does not receive an HTTP 200 response, your request to the Webhook API will fail with HTTP 400 and the webhook will not be created. If created successfully, the webhook will begin to receive event data after 1 minute.

Webhooks only support standard ports, port 80 for HTTP traffic and port 443 for HTTPS traffic. You will not be able to create a webhook using a non-standard port.

Request Body

name string required

Name for webhook

target string required

URL of the target to which to POST event batches. Only ports 80 for http and 443 for https can be set.

events array required

Array of event types this webhook will send. Use the Events Documentation endpoint to list the available event types.

active boolean, default is true

The status of the webhook. When false, the target will no longer receive batches.

custom_headers object

Object of custom headers to be used during POST requests to target.

exception_subaccounts array

Array of subaccount numbers to prevent receiving events in your webhook (only available for webhooks with Primary and All Subaccounts event source). Must not have duplicate values nor be empty. Integer values only. Max size: 10.

auth_type enum, default is none

Type of authentication to be used during POST requests to target. Read more about webhook authentication.

Possible Values: none, basic, oauth2

auth_request_details object

Object containing details needed to request authorization token for OAuth 2.0. This is required when auth_type is oauth2.

auth_credentials object

Request

POST /api/v1/webhooks/12affc24-f183-11e3-9234-3c15c2c818c2/validate

[
  {
    "msys": {}
  }
]

Response

{
  "results": {
    "msg": "Test POST to endpoint succeeded",
    "response": {
      "status": 200,
      "headers": {
        "Content-Type": "text/plain"
      },
      "body": "OK"
    }
  }
}

Validate a Webhook

POST/api/v1/webhooks/{id}/validate

Parameters

id uuid required

The validation request sends an example message event batch the target URL, validates that the target responds with HTTP 200, and returns information on the response received from the target.

Sample Batch

[
  {
    "msys": {}
  }
]

Request

GET /api/v1/webhooks/12affc24-f183-11e3-9234-3c15c2c818c2?timezone=America/New_York

Response

{
  "results": {
    "name": "Example webhook",
    "target": "http://client.example.com/example-webhook",
    "events": [
      "delivery",
      "injection",
      "open",
      "click"
    ],
    "exception_subaccounts": [
      "123"
    ],
    "auth_type": "oauth2",
    "auth_request_details": {
      "url": "https://oauth.myurl.com/tokens",
      "body": {
        "client_id": "<oauth client id>",
        "client_secret": "<oauth client secret>"
      }
    },
    "auth_credentials": {
      "access_token": "<oauth token>",
      "expires_in": 3600
    },
    "auth_token": "",
    "custom_headers": {
      "x-api-key": "abcd"
    },
    "active": true,
    "links": [
      {
        "href": "/api/v1/webhooks/12affc24-f183-11e3-9234-3c15c2c818c2/validate",
        "rel": "urn.msys.webhooks.validate",
        "method": [
          "POST"
        ]
      },
      {
        "href": "/api/v1/webhooks/12affc24-f183-11e3-9234-3c15c2c818c2/batch-status",
        "rel": "urn.msys.webhooks.batches",
        "method": [
          "GET"
        ]
      }
    ]
  }
}

Retrieve a Webhook

GET/api/v1/webhooks/{id}{?timezone}

Parameters

id uuid required

timezone string, default is UTC

Standard timezone identification string.

Request

GET /api/v1/webhooks/12affc24-f183-11e3-9234-3c15c2c818c2/batch-status?limit=1000

Response

{
  "results": [
    {
      "batch_id": "032d330540298f54f0e8bcc1373f3cfd",
      "ts": "2014-07-30T21:38:08.000Z",
      "attempts": 7,
      "response_code": "200",
      "latency": 160
    },
    {
      "batch_id": "13c6764994a8f6b4e29906d5712ca7d",
      "ts": "2014-07-30T20:38:08.000Z",
      "attempts": 2,
      "failure_code": "400",
      "response_code": "400",
      "latency": 210
    }
  ]
}

Retrieve Batch Status Information

GET/api/v1/webhooks/{id}/batch-status{?limit}

Parameters

id uuid required

limit int

Maximum number of results to return.

Batch Status Object

response_code number

Server response code of the webhook if successful.

batch_id number

Unique identifier of of the requested batch status.

batch_size number

Number of events inside of the batch.

ts string

Date the the batch was created was created.
Format: YYYY-MM-DDTHH:MM:SS+-HH:MM

failure_code number

Failure response code if the webhook failed during delivery.

webhook_id number

Unique identifier of the webhook associated with the batch.

attempts number

Number of failed attempts before the batch was delivered. Zero if succeeded on first attempt.

latency number

Duration in ms for the entire batch posting HTTP round-trip.

When SparkPost does not get a 200 response from your webhook consumer endpoint then the batch is failed and SparkPost will retry the batch multiple times for a period of 8 hours. Status information is provided on any failed batches and those that successed on retry. Batch status is available in the UI and API for 24 hours.

Request

PUT /api/v1/webhooks/12affc24-f183-11e3-9234-3c15c2c818c2

{
  "name": "Renamed webhook",
  "events": [
    "generation_rejection",
    "delay"
  ],
  "subaccount_id": 123,
  "auth_type": "none",
  "custom_headers": {
    "x-api-key": "abcd"
  }
}

Response

{
  "results": {
    "id": "12affc24-f183-11e3-9234-3c15c2c818c2",
    "links": [
      {
        "href": "/api/v1/webhooks/12affc24-f183-11e3-9234-3c15c2c818c2/validate",
        "rel": "urn.msys.webhooks.validate",
        "method": [
          "POST"
        ]
      }
    ]
  }
}

Update a Webhook

PUT/api/v1/webhooks/{id}

Parameters

id uuid required

Request Body

name string

Name for webhook.

target string

URL of the target to which to POST event batches. Only ports 80 for http and 443 for https can be set.

events array

Array of event types this webhook will send. Use the Events Documentation endpoint to list the available event types.

active boolean

The status of the webhook. When false, the target will no longer receive batches.

custom_headers object

Object of custom headers to be used during POST requests to target.

exception_subaccounts array

subaccount_id number

The new Subaccount to be set as the Event Source. Can be any integer number (use -1 for Primary and All Subaccounts or 0 for Primary Account only).

auth_type enum

Type of authentication to be used during POST requests to target. Read more about webhook authentication.

Possible Values: none, basic, oauth2

auth_request_details object

Object containing details needed to request authorization token for OAuth 2.0. This is required when auth_type is oauth2.

auth_credentials object

If you change to the target URL, a test POST request will be sent. If this request does not receive an HTTP 200 response, your request to the Webhooks API will fail with HTTP 400, and the webhook will not be updated.

Any batches already queued for delivery to this webhook will not be affected. For example, if you change the webhook's target URL, batches already queued for delivery will still be POSTed to the previous URL.

Request

DELETE /api/v1/webhooks/12affc24-f183-11e3-9234-3c15c2c818c2

Response

// Empty response body

Delete a Webhook

DELETE/api/v1/webhooks/{id}

Parameters

id uuid required

This will not affect any webhook batches that are already queued for delivery.

Request

GET /api/v1/webhooks?timezone=America/New_York

Response

{
  "results": [
    {
      "id": "a2b83490-10df-11e4-b670-c1ffa86371ff",
      "name": "Some webhook",
      "target": "http://client.example.com/some-webhook",
      "events": [
        "delivery",
        "injection",
        "open",
        "click"
      ],
      "auth_type": "basic",
      "auth_request_details": {},
      "auth_credentials": {
        "username": "basicuser",
        "password": "somepass"
      },
      "auth_token": "",
      "last_successful": "2014-08-01 16:09:15",
      "last_failure": "2014-06-01 15:15:45",
      "custom_headers": {
        "x-api-key": "abcd"
      },
      "active": true,
      "links": [
        {
          "href": "/api/v1/webhooks/a2b83490-10df-11e4-b670-c1ffa86371ff",
          "rel": "urn.msys.webhooks.webhook",
          "method": [
            "GET",
            "PUT"
          ]
        }
      ]
    },
    {
      "id": "12affc24-f183-11e3-9234-3c15c2c818c2",
      "name": "Example webhook",
      "target": "http://client.example.com/example-webhook",
      "events": [
        "delivery",
        "injection",
        "open",
        "click"
      ],
      "auth_type": "oauth2",
      "auth_request_details": {
        "url": "https://oauth.myurl.com/tokens",
        "body": {
          "client_id": "<oauth client id>",
          "client_secret": "<oauth client secret>"
        }
      },
      "auth_credentials": {
        "access_token": "<oauth token>",
        "expires_in": 3600
      },
      "auth_token": "",
      "last_successful": "2014-07-01 16:09:15",
      "last_failure": "2014-08-01 15:15:45",
      "active": true,
      "links": [
        {
          "href": "/api/v1/webhooks/12affc24-f183-11e3-9234-3c15c2c818c2",
          "rel": "urn.msys.webhooks.webhook",
          "method": [
            "GET",
            "PUT"
          ]
        }
      ]
    },
    {
      "id": "123456-abcd-efgh-7890-123445566778",
      "name": "Another webhook",
      "target": "http://client.example.com/another-example",
      "events": [
        "generation_rejection",
        "generation_failure"
      ],
      "auth_type": "none",
      "auth_request_details": {},
      "auth_credentials": {},
      "auth_token": "5ebe2294ecd0e0f08eab7690d2a6ee69",
      "active": true,
      "links": [
        {
          "href": "/api/v1/webhooks/123456-abcd-efgh-7890-123445566778",
          "rel": "urn.msys.webhooks.webhook",
          "method": [
            "GET",
            "PUT"
          ]
        }
      ]
    }
  ]
}

List all Webhooks

GET/api/v1/webhooks{?timezone}

Parameters

timezone string, default is UTC

Standard timezone identification string.

Returns a list of all your webhooks.

Documentation

Request

GET /api/v1/webhooks/events/documentation

Response

  {
    "results": {
      "message_event": { ... },
      "track_event": { ... },
      ...
    }
  }

Events Documentation

GET/api/v1/webhooks/events/documentation

Returns a list of descriptions of the events, event types, and event fields that could be included in a webhooks batches to your target URL.

Request

GET /api/v1/webhooks/events/samples?events=bounce

Response

  {
    "results": [
      {
        "msys": {
          "message_event": { ... }
        }
      }
    ]
  }

Event Samples

GET/api/v1/webhooks/events/samples{?events}

Parameters

events string

Event types for which to get a sample payload, use the Events Documentation endpoint to list the available event types, defaults to all event types.

Returns an example of the event data that will be posted by a webhook for the specified events.

The data that will arrive at your target URL during normal operation (as opposed to calls to this endpoint) will not contain the top level results key shown in the example response.