Events & webhooks

Events allow your system to know when something occurs within Seismic. When an event such as a LiveSend summary occurs, Seismic will send an HTTPS request to your application with a payload describing the event that occurred. You can use this information to make informed decisions like triggering a secondary action.

Event flow

Apps subscribing to events will follow a logical sequence:

  • User action triggers event
  • JSON payload sent to the defined request URL
  • Server acknowledges receipt of the event
  • Business logic performed
  • Carry out an action

Let's look at the following example using an email event.

  • A user sends a LiveSend
  • Your server (request url) receives an email event
  • Your server responds with a HTTP 200 OK
  • Your code processes the event to extract the recipients of the email event
  • Your server creates follow up tasks in CRM

Subscription creation

To utilize webhooks, we'll first need to create an event subscription.

965965

Toggling on the event subscription will enable you to define your result url. In order to save your event subscription we need to validate the url provided. To verify the url we'll send a request with a challenge parameter called challenge in the payload, and your endpoint must respond with that challenge value int ohe body to verify the url.

{
    "type": "verification",
    "challenge": "3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P"
}

📘

Request URL Verification

To draw a distinction from standard events vs verification events we have added a verification type to our verification requests.

This event does not require a specific OAuth scope or subscription. You'll automatically receive it whenever configuring a Request URL.

Once you receive the event, respond in plaintext with the challenge attribute value. In this example, that might be:

HTTP 200 OK
Content-type: text/plain
3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P

Responses for verification must be supplied with 3 seconds.

❗️

Retry policy

Seismic will retry failed deliveries for up to 24 hours with exponential backoff starting at 5 seconds (5, 25, 150...) before discarding it.

Once you have successfully configured your request url, you can subscribe to one to many events.

🚧

Adding or Removing events to an existing subscription

Any edits to a subscription will result in a new app version.

Seismic events have an event super-structure that all events will be wrapped around. Each event payload may differ event to event within the data object of the event itself.

Object

Description

id

Unique id of the event (GUID)

version

Version of the event

occurredAt

Timestamp of the event

tenantId

Tenant unique id (GUID)

tenantName

Tenant name

type

Webhook name

data

The container of the event details

Responding to Events

Apps should respond to the event request with an HTTP 2xx within 3 seconds. Failure to respond to the event with result in a perceived failure. After a failure, we will begin to exponentially backoff.

Any none 2xx response will be treated as a failure.

Failure Limits

While we strive to be tolerable to interruptions, we will proactively disable events subscriptions that are down for 7 days.

📘

Available events

We are continually evaluating adding new events to our subscription. As events are added we will add them to the change log. If there specific events you'd like to see feel free to submit those to your Seismic representative for consideration.