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

Enabling events

To utilize webhooks, we'll first need to enable events in your app.

Toggling on the enable events will enable you to define your event request url. In order to save your event settings 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 the 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 in the following order before discarding it.

• First retry: 1 minute after the initial request
• Second retry: 10 minutes after the first retry
• After the second retry, Seismic will retry every 1 hour for max 24 times.

Once you have successfully configured your request url, you can add one or many events.

🚧

Adding or Removing events

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.

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 retry sequence.

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.