SparkPost logodev

Relay Webhooks

Run in Postman
Import the SparkPost API as a Postman collection

Relay Webhooks are a way to instruct SparkPost to forward messages sent to an inbound domain to a target url for your own consumption. Before you create a relay webhook, first create and configure an inbound domain. The Relay Webhooks API provides the means to create, list, retrieve, update, and delete a relay webhook. To consume event webhooks see Event Webhooks

Relay Webhook Object

Example

{
  "id": "12013026328707075",
  "name": "Inbound Customer Replies",
  "target": "https://webhooks.customer.example/replies",
  "auth_token": "5ebe2294ecd0e0f08eab7690d2a6ee69",
  "match": {
    "protocol": "SMTP",
    "domain": "example.com"
  }
}

Attributes

id string

Unique ID

name string

Relay webhook name

target string

URL of the target to which to POST relay batches

auth_type enum

Type of authentication to be used during POST requests to target.

Possible Values: none, 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 and only grant_type of credentials is supported.

auth_token string

Authentication token to present in the X-MessageSystems-Webhook-Token header of POST requests to target. Use this token in your target application to confirm that data is coming from SparkPost.

match object

Restrict which inbound messages will be relayed to the target.

custom_headers object

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

Custom HTTP Headers Properties

The custom headers JSON object allows you to add up to five custom headers to your relay webhook. The custom_headers object may only be up to 3,000 bytes in size, and must be formatted as an object with keys as strings or numbers. Headers already used by SparkPost will not be allowed, and SparkPost may also disallow some HTTP headers for security reasons.

Adding Custom Headers

When creating (POST) or updating (PUT) a Relay Webhook:

{
  "custom_headers": {
    "header1": "value1",
    "header2": "value2"
  }
}

Removing Custom Headers

When updating (PUT) a Relay Webhook:

{
  "custom_headers": {}
}

Relay Webhook Payload

The following fields will be included in each object posted to the relay webhook's target:

Example

[
  {
    "msys": {
      "relay_message": {
        "content": {
          "email_rfc822": "Return-Path: <me@here.com>\r\nMIME-Version: 1.0\r\nFrom: me@here.com\r\nReceived: by 10.114.82.10 with HTTP; Mon, 4 Jul 2016 07:53:14 -0700 (PDT)\r\nDate: Mon, 4 Jul 2016 15:53:14 +0100\r\nMessage-ID: <484810298443-112311-xqxbby@mail.there.com>\r\nSubject: Relay webhooks rawk!\r\nTo: you@there.com\r\nContent-Type: multipart/alternative; boundary=deaddeaffeedf00fall45dbhail980dhypnot0ad\r\n\r\n--deaddeaffeedf00fall45dbhail980dhypnot0ad\r\nContent-Type: text/plain; charset=UTF-8\r\n\r\nHi there SparkPostians.\r\n\r\n--deaddeaffeedf00fall45dbhail980dhypnot0ad\r\nContent-Type: text/html; charset=UTF-8\r\n\r\n<p>Hi there <strong>SparkPostians</strong></p>\r\n\r\n--deaddeaffeedf00fall45dbhail980dhypnot0ad--\r\n",
          "email_rfc822_is_base64": false,
          "headers": [
            {
              "Return-Path": "<me@here.com>"
            },
            {
              "MIME-Version": "1.0"
            },
            {
              "From": "me@here.com"
            },
            {
              "Received": "by 10.114.82.10 with HTTP; Mon, 4 Jul 2016 07:53:14 -0700 (PDT)"
            },
            {
              "Date": "Mon, 4 Jul 2016 15:53:14 +0100"
            },
            {
              "Message-ID": "<484810298443-112311-xqxbby@mail.there.com>"
            },
            {
              "Subject": "Relay webhooks rawk!"
            },
            {
              "To": "you@there.com"
            }
          ],
          "html": "<p>Hi there <strong>SparkPostians</strong>.</p>",
          "subject": "We come in peace",
          "text": "Hi there SparkPostians.",
          "to": [
            "your@yourdomain.com"
          ]
        },
        "customer_id": "1337",
        "friendly_from": "me@here.com",
        "msg_from": "me@here.com",
        "rcpt_to": "you@there.com",
        "webhook_id": "4839201967643219"
      }
    }
  }
]

relay_message

content object

The content parsed from the incoming message.

friendly_from string

Email address used to compose the "From" header

msg_from string

SMTP envelope "MAIL FROM", matches "Return-Path" header address

rcpt_to string

SMTP envelope "RCPT TO"

webhook_id string

ID of the relay webhook which triggered this relay message.

protocol string, value is smtp

Protocol of the originating inbound message.

customer_id string

Customer ID of the customer that created the relay webhook.

Request

POST /api/v1/relay-webhooks
{
  "name": "Replies Webhook",
  "target": "https://webhooks.customer.example/replies",
  "auth_token": "5ebe2294ecd0e0f08eab7690d2a6ee69",
  "auth_type": "oauth2",
  "auth_request_details": {
    "url": "http://client.example.com/tokens",
    "body": {
      "client_id": "CLIENT123",
      "client_secret": "9sdfj791d2bsbf"
    }
  },
  "custom_headers": {
    "x-api-key": "abcd"
  },
  "match": {
    "domain": "email.example.com"
  }
}

Response

{
  "results": {
    "id": "12013026328707075"
  }
}

  {
      "errors": [
          {
              "message": "Domain 'domain' is not a registered inbound domain",
          }
      ]
  }

  {
      "errors": [
          {
              "message": "Domain 'domain' is already in use",
          }
      ]
  }

{
  "errors": [
    {
      "param": "custom_headers",
      "message": "Header is reserved and cannot be used",
      "value": "reserved-header"
    }
  ]
}

{
  "errors": [
    {
      "param": "custom_headers",
      "message": "You may only have up to 5 custom headers"
    }
  ]
}

Create a Relay Webhook

POST/api/v1/relay-webhooks

Create a relay webhook by providing a relay webhooks object as the POST request body.

Request Body

name string

Relay webhook name

target string required

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

auth_type enum, default is none

Type of authentication to be used during POST requests to target.

Possible Values: none, 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 and only grant_type of credentials is supported.

auth_token string

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

match object required

Restrict which inbound messages will be relayed to the target.

custom_headers object

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

Request

POST /api/v1/relay-webhooks/12013026328707075/validate

Response

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

Validate a Relay Webhook

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

Parameters

id string required

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

Example batch

Request

GET /api/v1/relay-webhooks/12013026328707075

Response

{
  "results": {
    "name": "Replies Webhook",
    "target": "https://webhooks.customer.example/replies",
    "auth_token": "5ebe2294ecd0e0f08eab7690d2a6ee69",
    "auth_type": "oauth2",
    "auth_request_details": {
      "url": "https://oauth.myurl.com/tokens",
      "body": {
        "client_id": "<oauth client id>",
        "client_secret": "<oauth client secret>"
      }
    },
    "custom_headers": {
      "x-api-key": "abcd"
    },
    "match": {
      "protocol": "SMTP",
      "domain": "email.example.com"
    }
  }
}

  {
      "errors": [
          {
              "message": "Unauthorized",
          }
      ]
  }

{
  "errors": [
    {
      "message": "Resource could not be found"
    }
  ]
}

Retrieve a Relay Webhook

GET/api/v1/relay-webhooks/{id}

Parameters

id string required

Retrieve a specific relay webhook by specifying the webhook ID in the URI path.

Request

PUT /api/v1/relay-webhooks/12013026328707075
{
  "name": "New Replies Webhook",
  "target": "https://webhook.customer.example/replies",
  "auth_token": "A different auth token",
  "auth_type": "none",
  "custom_headers": {
    "x-api-key": "abcd"
  },
  "match": {
    "domain": "email.a-different-domain.com"
  }
}

Response

{
  "results": {
    "id": "12013026328707075"
  }
}

  {
      "errors": [
          {
              "message": "Domain 'domain' is not a registered inbound domain",
          }
      ]
  }

{
  "errors": [
    {
      "message": "no valid fields in body"
    }
  ]
}

{
  "errors": [
    {
      "message": "Resource could not be found"
    }
  ]
}

  {
      "errors": [
          {
              "message": "Domain 'domain' is already in use",
          }
      ]
  }

Update a Relay Webhook

PUT/api/v1/relay-webhooks/{id}

Parameters

id string required

Update a relay webhook by specifying the webhook ID in the URI path.

Request Body

name string

Relay webhook name

target string

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

auth_token string

Authentication token to present in the X-MessageSystems-Webhook-Token header of 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, 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 and only grant_type of credentials is supported.

match object

Restrict which inbound messages will be relayed to the target.

custom_headers object

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

Request

DELETE /api/v1/relay-webhooks/12013026328707075

Response

// Empty response body

{
  "errors": [
    {
      "message": "Resource could not be found"
    }
  ]
}

Delete a Relay Webhook

DELETE/api/v1/relay-webhooks/{id}

Parameters

id string required

Delete a relay webhook by specifying the webhook ID in the URI path.

Request

GET /api/v1/relay-webhooks

Response

{
  "results": [
    {
      "id": "12013026328707075",
      "name": "Replies Webhook",
      "target": "https://webhooks.customer.example/replies",
      "auth_token": "5ebe2294ecd0e0f08eab7690d2a6ee69",
      "auth_type": "oauth2",
      "auth_request_details": {
        "url": "https://oauth.myurl.com/tokens",
        "body": {
          "client_id": "<oauth client id>",
          "client_secret": "<oauth client secret>"
        }
      },
      "custom_headers": {
        "x-webhook-source": "sparkpost"
      },
      "match": {
        "protocol": "SMTP",
        "domain": "email.example.com"
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "Unauthorized"
    }
  ]
}

List all Relay Webhooks

GET/api/v1/relay-webhooks

List all your relay webhooks.