Introduction

Webhooks are a way to receive notifications from Seismic when certain events occur. This allows you to build custom integrations with Seismic, such as updating a CRM system when a new piece of content is published.

Getting Started

To get started with Webhooks, you will need to create an app in Seismic and configure the webhook URL. This URL is where Seismic will send notifications when events occur.

Read the Events & webhooks for more information on how to setup an app and configure webhooks.

Event Types

Seismic support the following webhook events:

ContentManager

ContentProfile

CustomSchema

Email (Legacy)

LiveDoc

LiveDocExpress

Livesend (Legacy)

PlannerProject

PlannerRequest

PlannerTask

Program

ReadinessArchival

User

UserGroup

Workflow

Legacy Events

The following events are powered by our Legacy webhooks services, known internally as Webhooks v1. As the name suggests, this was our first pass at allowing apps to subscribe to events within Seismic.

• email - Details of an email that was sent
• email_enriched - Details of an email that was sent with additional enrichment
• interaction_session_summary - A summary of an interaction session
• interaction_session_summary_enriched - A summary of an interaction session with additional enrichment

Refer to the Legacy Webhooks for more information on these events.

Filtering Events

You can filter the events that you receive by specifying the filter expression in the app. The filter expression is a JSONPath expression that is used to filter the events that are sent to the webhook URL.

Note: The filter expression uses Newtonsoft.Json.Linq.JToken.SelectTokens method to filter the events. This implements the original Stefan Goessner's JSONPath implementation which has some limitations. Read the documentation carefully to understand what is supported.

For example, to only receive ContentManagerCreateFileV1 events where the event occurred in a specific TeamSite you can use the following filter expression:

$.data..[?(@.teamSiteId == '1')]

Supported JsonPath Filter Expressions

Refer to the below steps to learn how to write a filter expression.

Suppose you have the following JSON payload:

{
    "id": "26a6d425-d0f1-4002-b7ca-ee3c1f64c431",
    "version": "DemoEventV1",
    "occurredAt": "2024-03-31T09:13:57.948Z",
    "tenantId": "234b9f0d-853d-4210-b5d2-b0574e003fcc",
    "tenantName": "demo",
    "data": {
        "contentId": "foo",
        "followers": [
            {
                "userId": "b26fa7a6-5060-7ce1-8cf2-9fc6a414dfdf",
                "userId": "d8c64a61-ca1a-4535-8877-c0d0ba170e38"
            }
        ]
    },
    "application": "DemoService",
    "productArea": "Demo"
}

Suppose you want to filter the events where the contentId is foo.

1. Start with the root object $.

$

2. Navigate to the data object.

$.data

3. Convert the data object to an array by using the recursive descent operator ... This step is important as the script expression ?() only works with arrays.

$.data..

4. Add subscript operator [].

$.data..[]

5. Add the script expression [?()] inside the subscript operator.

$.data..[?()]

6. The final step is to add the filter expression @.contentId == 'foo' inside the script expression [?()].
   @ refers to the object being evaluated.

$.data..[?(@.contentId == 'foo')]

This expression will evaluate to true and the event will be sent to the webhook URL if the contentId is foo.

More examples of filter expressions

Filter events where the tenantId is 234b9f0d-853d-4210-b5d2-b0574e003fcc.

$..[?(@.tenantId == '234b9f0d-853d-4210-b5d2-b0574e003fcc')]

Filter events where the tenantName is demo.

$..[?(@.tenantName == 'demo')]

ContentManagerCreateFileV1

See the documentation for the ContentManagerCreateFileV1 event to understand the structure of the event.

Filter events where the contentId is foo.

$.data..[?(@.contentId == '5a5699ac-49a7-43ba-82cc-0eea22cea051')]

Filter events where the teamSiteId is 1.

$.data..[?(@.teamSiteId == '1')]

Filter events where content format is pptx.

$.data..[?(@.format == 'PPTX')]

LiveDocCompletedV2

See the documentation for the LiveDocCompletedV2 event to understand the structure of the event.

Filter events where the LiveDoc generation requestId is c9c564af-e5c9-4a4b-ac55-4f9f85662888.

$.data..[?(@.requestId == 'c9c564af-e5c9-4a4b-ac55-4f9f85662888')]

Filter events where the LiveDoc generation requestId is c9c564af-e5c9-4a4b-ac55-4f9f85662888 and output format is PPTX.

$.data..[?(@.requestId == 'c9c564af-e5c9-4a4b-ac55-4f9f85662888' && @.output.format == 'PPTX')]

Filter events where the LiveDoc generation requestId is c9c564af-e5c9-4a4b-ac55-4f9f85662888 and output format is PPTX and the status is Generated.

$.data..[?(@.requestId == 'c9c564af-e5c9-4a4b-ac55-4f9f85662888' && @.output.format == 'PPTX' && @.status == 'Generated')]

Webhook Security

Seismic sends a x-seismic-signature header with each webhook request. This header contains a HMAC signature of the request body. You can use this signature to verify that the request was sent by Seismic and not a third party.

To verify the signature, you need to calculate the HMAC signature of the request body using the signing secret that you generated in the app. You can then compare this signature with the x-seismic-signature header to verify the request.

Refer to the documentation Signing secret validation to understand how to verify the signature.

Signing secret rotation

In case you want to change the signing secret, you can do so by generating a new secret in the app. This will generate a new signing secret and push the current secret to the history.

This will update the signature in the webhook request within 30 minutes to use the new signing secret. Seismic will add one additional header x-seismic-signature-old with the HMAC signature of the request body using the old signing secret. You can use this signature to verify the request using the old signing secret. This will allow you to transition to the new signing secret without any downtime. Once the transition is complete, you can delete the old signing secret from the app.

Webhook Retry Policy

Seismic will retry sending the webhook notification if the request fails. The retry policy is as follows:

• Total number of retries: 26
• First retry: 1 minute after the initial request
• Second retry: 10 minutes after the first retry
• After the second retry, Seismic will retry sending the notification every 1 hour for 24 more times.

After the total number of retries is exhausted, Seismic will stop sending the notification.