Webhooks

The Webhooks API provides the means to create, review, update, and delete webhooks, which enables you to receive push updates of the raw events generated by SparkPost. This support article describes how to set up a webhook in the SparkPost UI.

The following are key operational details:

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

  • When using ‘oauth2’, auth_request_details must be set by the user (example: { "url": "https://oauth.myurl.com/tokens", "body": { "client_id": "<oauth client id>", "client_secret": "<oauth client secret>" }}). Additionally, auth_credentials is set by the system and cannot be configured by the user.

  • When using ‘basic’ auth, auth_credentials must be set by the user and should be an object containing “username” (required) and “password” (optional). (example: { "username": "basicauthuser", "password": "mypassword" })

Using Postman

If you use Postman you can click the following button to import the SparkPost API as a collection:

Run in Postman

Webhooks Object Properties

Property Type Description Required Notes
name string User-friendly name for webhook yes example: Example webhook
target string URL of the target to which to POST event batches yes When a webhook is created or updated with a change to this property, a test POST request is sent to the given URL. The target URL must accept the connection and respond with HTTP 200; otherwise, your request to the Webhook API will fail with HTTP 400, and the requested change will not be applied.
example: http://client.example.com/example-webhook
events array Array of event types this webhook will receive yes Use the Webhooks Events endpoint to list the available event types.
example: ["delivery", "injection", "open", "click"]
active boolean Describes status of the webhook no Defaults to true, when false the target will no longer receive batches
custom_headers JSON Object of custom headers to be used during POST requests to target no example: {"x-api-key" : "abcd"}
auth_type string Type of authentication to be used during POST requests to target no examples: none, basic, oauth2
auth_request_details JSON Object containing details needed to request authorization credentials, as necessary no example: { "url": "https://oauth.myurl.com/tokens", "body": { "client_id": "<oauth client id>", "client_secret": "<oauth client secret>" }}
auth_credentials JSON Object containing credentials needed to make authorized POST requests to target no examples: { "access_token": "<oauth token>", expires_in: 3600 }, { "username": "basicauthuser", "password": "mypassword" }
auth_token string Authentication token to present in the X-MessageSystems-Webhook-Token header of POST requests to target no Use this token in your target application to confirm that data is coming from the Webhooks API.
example: 5ebe2294ecd0e0f08eab7690d2a6ee69

Deprecated in favor of the auth_type field.

The SparkPost webhooks API uses MaxMind software MaxMind License

Events Documentation

Documentation

GET/api/v1/webhooks/events/documentation

List descriptions of the events, event types, and event fields that could be included in a Webhooks post to your target URL.

Examples

Request

GET /api/v1/webhooks/events/documentation


Events Samples

Samples

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

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

Example: bounce

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

Note: 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.
SparkPost Enterprise customers may find the delv_method key useful to differentiate between Email, Push, and SMS type events.

Examples

Request

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


Create

Create a Webhook

POST/api/v1/webhooks

Create a webhook by providing a webhooks object as the POST request body. On creation, events will begin to be pushed to the target URL specified in the POST request body.

As described in “Webhooks Object Properties”, webhook creation entails a test POST request to the URL given as the target value. 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.

Examples

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 (HTTP status code: 200)

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

Response (HTTP status code: 400)

{
  "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
      }
    }
  ]
}

Retrieve

Retrieve Webhook Details

GET/api/v1/webhooks/{id}{?timezone}
URI Parameters
id(required)  

UUID identifying a webhook

Example: 12affc24-f183-11e3-9234-3c15c2c818c2
timezone

Standard timezone identification string, defaults to UTC

Default: UTC

Example: America/New_York

Retrieve details about a webhook by specifying its id in the URI path.

Examples

Request

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

Response (HTTP status code: 200)

{
  "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": "http://www.messagesystems-api-url.com/api/v1/webhooks/12affc24-f183-11e3-9234-3c15c2c818c2/validate",
        "rel": "urn.msys.webhooks.validate",
        "method": [
          "POST"
        ]
      },
      {
        "href": "http://www.messagesystems-api-url.com/api/v1/webhooks/12affc24-f183-11e3-9234-3c15c2c818c2/batch-status",
        "rel": "urn.msys.webhooks.batches",
        "method": [
          "GET"
        ]
      }
    ]
  }
}

List

List all Webhooks

GET/api/v1/webhooks{?timezone}
URI Parameters
timezone

Standard timezone identification string, defaults to UTC

Default: UTC

Example: America/New_York

List all currently existing webhooks.

Examples

Request

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

Response (HTTP status code: 200)

{
  "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": "http://www.messagesystems-api-url.com/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": "http://www.messagesystems-api-url.com/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": "http://www.messagesystems-api-url.com/api/v1/webhooks/123456-abcd-efgh-7890-123445566778",
          "rel": "urn.msys.webhooks.webhook",
          "method": [
            "GET",
            "PUT"
          ]
        }
      ]
    }
  ]
}

Update and Delete

Update a Webhook

PUT/api/v1/webhooks/{id}
URI Parameters
id(required)  

UUID identifying a webhook

Example: 12affc24-f183-11e3-9234-3c15c2c818c2

Update a webhook’s properties by specifying its id in the URI path and use a webhooks object as the PUT request body.

Note: 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.

As described in “Webhooks Object Properties”, a change to the target value entails a test POST request to the URL given. 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 modified.

Examples

Request

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

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

Response (HTTP status code: 200)

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

Delete a Webhook

DELETE/api/v1/webhooks/{id}
URI Parameters
id(required)  

UUID identifying a webhook

Example: 12affc24-f183-11e3-9234-3c15c2c818c2

Delete a webhook from the system by specifying its id in the URI path.

The system will stop pushing data to the target URL after the batches currently queued to be delivered are drained.

Examples

Request

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

Response (HTTP status code: 204)

Empty response body

Validate

Validate a Webhook

POST/api/v1/webhooks/{id}/validate
URI Parameters
id(required)  

UUID identifying a webhook

Example: 12affc24-f183-11e3-9234-3c15c2c818c2

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

Message Properties

Property Type Description Required Notes
message object Example batch to send yes example: [ { "msys": {} } ]

Examples

Request

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

[
  {
    "msys": {}
  }
]

Response (HTTP status code: 200)

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

Batch Status

Retrieve Status Information

GET/api/v1/webhooks/{id}/batch-status{?limit}
URI Parameters
id(required)  

UUID identifying a webhook

Example: 12affc24-f183-11e3-9234-3c15c2c818c2
limit

Maximum number of results to return. Defaults to 1000.

Example: 1000

Retrieve status information regarding batches that have been generated for the given webhook by specifying its id in the URI path. 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.

Examples

Request

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

Response (HTTP status code: 200)

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