Webhooks

Run in Postman
Import the SparkPost API as a Postman collection

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).

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 auditing and prevention of processing duplicate batches.

  • 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 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": {
      "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": "127.0.0.1",
      "ip_pool": "Example-Ip-Pool",
      "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",
      "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",
      "recv_method": "esmtp",
      "routing_domain": "example.com",
      "sending_ip": "127.0.0.1",
      "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

 

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.

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.

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.

recv_method

Protocol by which SparkPost received this message.

routing_domain

Domain receiving this message.

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,
  "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.

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"
    }
  },
  "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.

Request Body

name string required

Name for webhook

target string required

URL of the target to which to POST event batches.

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.

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

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.

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"
    ],
    "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.

Returns the status information for the batches that have been generated. Status information includes the successes of batches that previously failed to reach the webhook's target URL and batches that are currently in a failed state.

Request

PUT /api/v1/webhooks/12affc24-f183-11e3-9234-3c15c2c818c2
{
  "name": "Renamed webhook",
  "events": [
    "generation_rejection",
    "delay"
  ],
  "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.

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.

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.

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.