Events and webhooks

The Signicat Events service lets you create and manage subscriptions to events published by Signicat services.

Try it in the Signicat Dashboard

To access the events service, go to Signicat Dashboard > Settings > Events.

What are 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.

Once you subscribe to an event, you 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 automatically downloads the signed document. With an event subscription, you do not need to poll our APIs to determine 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.

Example: Event when a sign order is 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"
  ]
}

Subscriptions

From the Subscriptions page, you can:

• Create new subscriptions
• Manage existing subscriptions
• Test test your events

Subscription types

We support a variety of subscription types that you can use for event delivery. To learn more, see the sections below.

Webhooks

You can subscribe to certain events on your Signicat account by sending a payload to the webhook's configured URL, if you have a public endpoint that we can reach. To do this, see Set up webhook in the Signicat Dashboard.

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.

Add a secret token

We recommend that you add a secret token to your webhook when creating the subscription. To do this:

1. On the Set up webhook page, tick the box marked Secret. A secret token is then automatically generated for you.
2. Copy the secret token. You can then use it to validate that the event payload is coming from Signicat.

Validate 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. Any added whitespace or ordering of properties will result in an invalid hash.
const payload = '{"message":"Hello, world"}';

const hmac = crypto.createHmac("sha256", secret);
const signature = hmac.update(payload).digest("hex").toUpperCase();
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. To do this, see Set up Azure Service Bus in the Signicat Dashboard.

Google Pub/Sub

You can subscribe to certain events on your Signicat account to push events to your Google Pub/Sub topic. To do this, see Set up Google Pub/Sub in the Signicat Dashboard.

Signicat Mint

You can subscribe to certain events on your Signicat account to trigger a Mint flow. To do this, see Set up Mint in the Signicat Dashboard.

Add a subscription

1. From the Events overview, click the Add subscription button.
2. Select a subscription type from the list of connections.
   Want to learn more?

   To learn more about specific subscription types, see the Subscription types section.

3. Complete the required information specific to that connection type.
   How do tags work?

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

   • 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 picks up all events that start with that tag. For example, the tag test-* picks up events that start with test-tag or test-event.
4. Click the Add button to create the subscription.

Manage a subscription

To make changes to existing subscriptions that you have set up:

1. From the Subscriptions overview, click on the subscription that you want to make changes to.
2. On the subscription details page, make your desired changes.
3. To save your changes, click the Update button.

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 test your subscriptions and event code handling.

To use this feature:

1. From the Subscriptions overview, click the Test events button.
2. Select a subscription from the first dropdown menu.
3. Select an event type from the second dropdown menu.
4. 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

From the Events page, you can:

• View a list of your event deliveries from the events that you have subscribed to.
• View the details of a particular event by clicking on it. Here, you can find the request and response body for the event.

Event types

The list of event types that we support is constantly evolving. You can see the full list of supported events available when you set up a new subscription. To do this:

1. From the Events overview, 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.

Preview the JSON payload

You can preview what the JSON payload looks like for each event when you set up a new subscription. To do this:

1. When seeing the full list of events as described above, click the Preview button next to the event that you would like to preview.
2. The JSON payload appears on the right-hand side.

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 is disabled and no further events are 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 is 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.

To learn about how to do this, see our Signicat Events Management API reference documentation. It 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