Events and webhooks

About Signicat events

Events are our way of letting you know when something happens in one of our services. For example, when a document is signed, or if a change is made to your account, then we create an event.

The Signicat Events service lets you subscribe to events published by Signicat services. Once you subscribe to an event, you will automatically receive information about this event into your system.

We support delivering events using:

• Webhooks
• Microsoft Azure Service Bus
• Google Pub/Sub
• Signicat Mint

Example use case

When a document is signed, your system could automatically download the signed document without the need for polling our APIs when the documents are ready for download.

What does an event look like?

An event contains nine fields, as illustrated in the table below.

Events follow the same structure across all Signicat services, with the exception of the event data (eventData) field. This field is given as a JSON object and varies depending on the type of event that is sent.

Field name	Description	Type
id	The ID of the event.	String
timestamp	The timestamp when the event was created.	ISO 8601 date string
sender	The service which is sending the event.	String
eventName	The name of the event.	String
eventData	The event data. You can see the structure of this for each event type in the Signicat Dashboard.	JSON
accountId	The account ID which the event is sent in the context of.	String
organizationId	The organisation ID which the event is sent in the context of. Note: This can be null.	String
expiresAt	The timestamp when the event expires. Note: There are no more retries after this timestamp.	ISO 8601 date string
tags	Optional tags that can be included in the event. Note: You add tags by setting them in the request to the service publishing the events.	String array

Example: Event when a sign order is considered completed

{
  "id": "82fa52a9bc7549438b8c6aee71569fa7",
  "timestamp": "2023-11-13T11:38:10.7302363Z",
  "sender": "signature-api",
  "eventName": "order.completed",
  "eventData": //Json object,
  "accountId": "a-spge-IL9J9flqic18sh4TsUAo",
  "organizationId": null,
  "expiresAt": "2023-11-13T11:38:40.7302345Z",
  "tags": [
    "mock"
  ]
}

Get started with the events service

You can create and manage event subscriptions in the Signicat Dashboard. To do this:

1. Log in to the Signicat Dashboard.
2. Navigate to the Events service.
   Where can I find the Events service?

   From the Signicat Dashboard, you can access the Events service in two ways:

   • Under the Management heading, click Events.
   • In the left-side menu, expand the Settings dropdown menu, then click Events.

Screenshot showing 'Events' page in Events service

In the Signicat Dashboard, you can interact with the Events service through two main pages; Events and Subscriptions. You can navigate between these pages using the left-side menu.

Subscriptions

On the Subscriptions page, you can create new subscriptions, manage existing subscriptions and also test your events.

Subscription types

Webhooks

If you have a public endpoint that we can reach, then you can use webhooks to subscribe to certain events on your Signicat account. This is done by sending a payload to the webhook's configured URL.

The URL must respond with a HTTP status code of 200-299 within 15 seconds, otherwise the webhook delivery is considered failed and may be retried. For further details, see the error handling section.

Set up a new subscription

To set up a new subscription with a webhook, you can follow the steps outlined in How to add a subscription.

Our recommendation

For webhooks, you have the option to add a secret token; we recommend that you do this.

You can find out how to do this in the Creating your secret token section.

Creating your secret token

We recommend that you add a secret token to your webhook. This can be done in the Signicat Dashboard when you are creating the subscription.

1. On the Setup Webhook page, tick the box marked Secret.
   

   Screenshot showing how to add secret in Events service

2. A secret token is automatically generated for you.
3. Copy the secret token. You can then use it to validate that the event payload is coming from Signicat.

Validating payloads

Using your secret token, we create a HMAC-SHA256 signature of the request body. All requests include a X-Signicat-Signature header containing this signature, which you then can use to validate the integrity of the payload and its origin.

To validate the request, compute the HMAC digest using your secret token as the signing key and ensure that it matches the signature from the header.

Example: How to generate signature with Node.js

const crypto = require("crypto");
const secret = "your-secret-token";

// It is important to use raw request body and not deserialize it
const payload = '{"message":"Hello, world"}';

const hmac = crypto.createHmac("sha256", secret);
const signature = hmac.update(payload).digest("hex");
console.log(signature); // => def564b8df06ae55c788493cb414068b2cf017385d96ecb39aa3e844fdbbcdea

Azure Service Bus

You can subscribe to certain events on your Signicat account to push events to your Azure Service Bus queue.

Google Pub/Sub

You can subscribe to certain events on your Signicat account to push events to your Google Pub/Sub topic.

Signicat Mint

You can subscribe to certain events on your Signicat account to trigger a Mint flow.

How to add a subscription

1. You can add a new subscription by clicking the Add subscription button in the middle of either the Events or Subscriptions page.
   

   Screenshot showing 'Subscriptions' page in Events service

   Note

   If you already have an existing subscription, then you can add a new one using the Add subscription button on the top right of the Subscriptions page.

2. Select a subscription type from the list of connections.
   Note

   For more specific information about each connection type, see the Subscription types section.

3. Add a name for your subscription in the Name* field.
4. Complete the required information specific to that connection type.
   Example

   If you were setting up a webhook connection, you would need to complete the Webhook URL* field.

5. Optionally, you can add tags in the Tag filter field. This means that we will then only forward events that include the specified tags.
   Note

   • The event has to include all of the specified tags in the tag filter in order for it to be forwarded.
   • If you end the tag with an asterisk, it will pick up all events that start with that tag. For example, the tag test-* would be able to pick up events that start with test-tag or test-event.
6. Select whether you would like the subscription to be immediately active or not.
7. Use the radio buttons to select whether you would like to listen to events from all available Signicat services, or selected events of your choosing instead.
8. If you have chosen Selected events, then you will be presented with a list of dropdown menus which correspond to different services and corresponding events. Tick all of the boxes that you wish to listen to for this subscription.
9. Click the Add button to create the subscription.

Success!

You have now set up a subscription. You will be taken back to the Subscriptions page where you can view and manage all of your subscriptions.

You can view the event deliveries on the Events page.

How to manage a subscription

You can make changes to existing subscriptions that you have set up. To do this:

1. Go to the Subscriptions page.
2. Click on the subscription that you wish to make changes to. You will be taken to the subscription details page.
   

   Screenshot showing how to manage subscriptions in Events service

3. Make your desired changes.
4. Click the Update button to save these changes.

How to test your events

Our event testing feature makes it possible to test certain events from the Signicat Dashboard. This means that:

• when you are integrating, you can create a mock event instead of triggering the actual event.
• You can use this to test your subscriptions and event code handling.

To do this:

1. Go to the Subscriptions page.
2. Click the Test events button.
   

   Screenshot showing how to test events in Events service

3. Select a subscription from the first dropdown menu.
4. Select an event type from the second dropdown menu.
5. Click Send.

Success!

You have now created a mock event. You can view the request body that has been produced for this mock event, so that you can see how it looks before you test.

Events

On the Events page, you can view a list of your event deliveries from the events that you have subscribed to. You can view the details of a particular event by clicking on it.

Note

You will find the request and response body for the event in the event details.

Event types

The list of event types that we support will constantly evolve. You can see the full list of supported events available when you set up a new subscription.

1. Click the Add subscription button.
2. Choose the subscription type that you want to set up.
3. Click the Selected events radio button under the Listen to section.

Here you can see a list of the events that we currently support.

Preview the JSON payload

You can preview what the JSON payload will look like for each event when you set up a new subscription.

1. Click the Preview button next to the event that you would like to preview.
2. The JSON payload will appear on the right-hand side.

Screenshot showing how to preview an event's JSON payload in Events service

Error handling

An event delivery is considered failed if we are unable to deliver the event. This includes network issues, timeouts and HTTP status codes other than 200-299.

• In general, failures caused by network errors are retried, whereas failures caused by misconfiguration are not retried. This means that only HTTP status codes of 429 and 500-599 are retried.
• If a webhook responds with the HTTP status code 410 Gone, then the subscription will be disabled and no further events will be delivered.
• The time between each delivery attempt starts at approximately one second and rapidly increases towards 24 hours, for up to five days.
• If a webhook responds with a Retry-After header, then the next delivery attempt will not be retried for at least the duration specified in the header.

API integration

It is also possible for you to manage your event subscriptions using our API.

Our Signicat Events Management API reference documentation contains information about available endpoints and properties, in addition to sample requests and responses.

Signicat Events Management API

Create and manage subscriptions to events published by Signicat services