Developer Pages

# Events and webhooks

Page contents

# Overview

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 these events from Signicat services. Once you have subscribed to an event, you can automatically receive business critical events from Signicat into your system.

We support delivering events using:

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

Note

We plan to support more connections in the future. You can see the full list of subscription types available when you set up a new subscription in the Signicat Dashboard.

See How to add a subscription to find out how to do this.

# 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.

# 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 (opens new window).
  2. In the top navigation bar, use the dropdown menu next to your organisation name to select the account that you want to make changes to.
  3. On the Topics page select Events.
  4. You are now in the events section of the Signicat Dashboard.

Events service - events page click-to-zoom

The events section of the Signicat Dashboard is comprised of two main pages, Events and Subscriptions. You can navigate between these sections using the left-side menu.

# Subscriptions

On the Subscriptions (opens new window) 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.

# 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 next step.

# 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.

Events service - preview a JSON payload for an event click-to-zoom

  1. A secret token is automatically generated for you.
  2. 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.

Below is an example of how to generate the signature with Node.js:

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

const payload = {
  "message": "Hello, world"
};

const hmac = crypto.createHmac('sha256', secret);
const signature = hmac.update(JSON.stringify(payload)).digest('hex').toUpperCase();
console.log(signature) // => DF31B9F7D1645BD532F1F1C8F3EA80E3271DCD3C2A4D015115F9E20E5982FEE9

# 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.

# 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 (opens new window) or Subscriptions (opens new window) page.

Events service - subscriptions page click-to-zoom

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 (opens new window) page.

  1. You must now select a subscription type from the list of connections.

    See Subscription types for more specific information about each connection type.

  2. Add a name for your subscription in the Name* field.

  3. Complete the required information specific to that connection type. For example, if you were setting up a webhook connection, you would need to complete the Webhook URL* field.

  4. Select whether you would like the subscription to be immediately active or not.

  5. 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.

  6. 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.

  7. Click the Add button to create the subscription.

Success!

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

You can view the event deliveries on the Events (opens new window) 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 (opens new window) page.
  2. Click on the subscription that you wish to make changes to. You will be taken to the subscription details page.

Events service - subscriptions page - manage click-to-zoom

  1. Make your desired changes.
  2. Click the Update button to save these changes.

# How to test your events

We have integrated a feature for events in the Dashboard where you can test certain events. 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 (opens new window) page.
  2. Click the Test events button.

Events service - subscriptions page - test click-to-zoom

  1. Select a subscription from the first dropdown menu.
  2. Select an event type from the second dropdown menu.
  3. 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 (opens new window) 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.

Events service - preview a JSON payload for an event click-to-zoom

# Event delivery retries

In case the event cannot be delivered due to issues at the subscription endpoint, we have the following automatic retry logic in place:

Retry attempt number Wait time before next try
1-2 15 seconds
3-4 1 minute
5 2 minutes
6 5 minutes
7-10 15 minutes
11-15 60 minutes
16-20 24 hours
21+ No further attempts
Last updated: 12/07/2023 08:21 UTC

← Communication →