Defining Webhooks

August 3, 2018 Contributors

The SparkPost webhooks interface allows you to push web hook events of your choice to your own endpoint for processing.  You can also retrieve event level data through the Message Events API.

There are three (3) main categories of webhook events in SparkPost:

  1. Message Events: Describe the lifecycle of a message (transmission), including: injection, delivery, and disposition
  2. Generation Events: Provide insight into message creation failures or rejections (by SparkPost)
  3. Engagement Events: Describe what recipients "do" with your email, such as: opens (renders) and clicks

Each of the above categories have a variety of event types, each with a unique set of fields that will provide information to your webhook event consumer. Read the full list of event-to-field mappings in SparkPost webhooks.

How to define a Webhook in SparkPost

There are two ways to create a webhook in SparkPost: Using the SparkPost Webhook API or using the SparkPost UI (directions below).

  1. Login to SparkPost
  2. Navigate to Webhooks
  3. Click on the "New Webhook" button
  4. Set the following values:
    1. Webhook Name: human friendly name for your webhook
    2. Target URL : The URL where your webhook event consumer resides and the path to the event handler. Example: http[s]://your.domain.tld/webhook/event/handler
    3. Basic Auth or OAuth  [OPTIONAL]: The Authentication Token is still there for existing webhooks, but has been deprecated for new ones.
    4. Events:
      1. All: The webhook will receive ALL events from ALL webhook categories
      2. Select: You can choose which events you want to be sent to your webhook consumer
  5. Click the Add Webhook button, and your webhook will be saved.
  6. If you want to test that the webhook is working, click the "Test" tab.
  7. If you want to modify your webhook, click the "Setting" tab.
  8. If you want to delete this webook, click Delete.