Webhooks

Subscribe to interesting events

You may want to be notified every time something interesting happens in your account. That’s what webhooks are for.

Configure a webhook endpoint

From your account’s Developer menu, you can configure the URL you want to be notified on as well as the events you want to subscribe to.

The list of webhookable events is as follows:

apikey events

• apikey.created
• apikey.updated
• apikey.deleted

transaction events

• transaction.lifecycle.created
• transaction.lifecycle.started
• transaction.lifecycle.paused
• transaction.lifecycle.cancelled
• transaction.lifecycle.expired
• transaction.lifecycle.completed
• transaction.chat.message.received

participant action events

• action.opened
• action.closed
• action.stalled
• action.manualreminder.sent
• action.reminder.sent
• action.waitingperiod.cancelled
• action.waitingperiod.ended

Note that a participant’s action can be stalled for one of the following reasons:

• action_refusal (the participant refused to authenticate on the signature page)
• signature_refusal (the participant refused a document to sign)
• consultation_refusal (the participant refused a document to read)
• review_refusal (the participant refused a document to review)

The stall reason is indicated in the action.stalled event payload.

identity validation events

• identity-validation.processed

To create a webhook endpoint, navigate to the Webhook endpoints section and click the “Create endpoint” button.

In the modal window:

1. Name the endpoint.
2. Enter the URL you want to be notified on (only secure URLs are accepted).
3. Select the events you want to subscribe to (you can select more than one).
4. Create the endpoint.

The webhook endpoint you just created now displays in your endpoints dashboard.
From the endpoints dashboard, you can view information about each endpoint (name, URL, creation date and success rate of sent webhooks). You can also edit or delete endpoints from the endpoint menu.

From the dashboard, if you click on an endpoint, you can view its details:

• The endpoint ID
• The date it was created
• The notification URL
• The events associated to this endpoint

View webhooks

To view all webhooks sent to the configured endpoints, navigate to the Webhooks section.

On the webhooks list, you can see, among other information, their state (whether they were sent correctly or not) and reschedule manually the sending of webhooks that could not be sent. When the system fails to send a webhook, it will retry sending after:

• 1 minute
• 5 minutes
• 30 minutes
• 2 hours
• 6 hours
• 24 hours
• 48 hours

During all the retry period, the webhook state is pending. If the webhook could not be sent correctly after all retries, its state switches to failed.

From the webhooks dashboard, you can filter webhooks to refine your search:

- By period
Select the search format for the period, either Before a specific date or Between two specific dates and enter a date and time.

- By state
You can filter on one or more states among successful, pending or failed webhooks.

- By endpoint
Use to retrieve webhooks sent to a specific URL.

- By event type
Use to retrieve webhooks sent for a specific event type.

- By event ID
Use to retrieve the webhook associated to one specific event.

Display information about a specific webhook

From the webhook dashboard, you can click a webhook to view:

- Its detailed information:

• The webhook ID
• Its creation date
• The name of the endpoint it is associated to
• Its state (successful, pending or failed)
• The event ID associated to the webhook
• The event type associated to the webhook
• The next scheduled retry, if state is pending, along with the possibility to resend manually
• The response time, expressed in milliseconds

- Its sending history, including:

• Webhook state
• Webhook URL
• The HTTP status
• The sending date

Webhook authentication

When Universign sends a webhook, the request body is signed and the signature is added to the request header so you can verify its authenticity and integrity. The signature format used by Universign is JWS (JSON Web Signature) with detached content as described in the RFC7515 standard.

Signature structure

The JWS is added to the webhook request header in the x-jws-signature header field. The JWS has 3 sections:

• The header
• The data
• The signature itself

Note: Since a JWS with detached content is used, the data section is not present in the JWS but corresponds to the request body in JSON format.

In the example below, the signature as it displays in the request header:

• Highlighted in green is the base64URL-encoded signature header. It contains the algorithm as well as the ID of the public key that was used to sign.
• Between the two dots, the data section is empty and moved in the request body as shown in the screenshot below.
• Highlighted in yellow is the base64URL-encoded signature itself.

The JSON request body:

{
  "object": "event",
  "id": "evt_x7yrPr1rXJBn",
  "type": "transaction.lifecycle.created",
  "payload": {
    "object": {
      "object": "transaction",
      "id": "tx_x7yrPr1a566A",
      "folder_id": "fol_MJQbbKe5PV7d",
      "created_at": "2022-03-15T18:08:16.222Z",
      "started_at": null,
      "closed_at": null,
      "expires_at": null,
      "duration": 20160,
      "name": "tx_x7yrPr1a566A",
      "folder_name": "Mon dossier",
      "stalled": false,
      "language": "fr",
      "sender_name_display": "name_email",
      "creator": {
        "name": "Jane Doe",
        "email": "Jane.Doe@company.com",
        "workspace_name": "My workspace",
        "api_key_name": null
      },
      "state": "draft",
      "participants": [],
      "sealers": [],
      "documents": [],
      "instructions": {
        "sequencing": [],
        "signatures": [],
        "reviews": []
      },
      "actions": [],
      "metadata": {},
      "progress_value": 0,
      "ongoing_conversation": false,
      "has_unread_message": false,
      "origin": "webapp",
      "carbon_copy": [],
      "watchers": [
        "mbr_DDmnn6rrKZa3"
      ],
      "cancel_reason": null,
      "cancel_code": null
    }
  },
  "traceId": null,
  "createdAt": 1647367696.238
}

The input to the signature is the base64URL-encoded signature header concatenated with the base64URL-encoded request body.

How to verify the webhook signature:

1. Retrieve the key ID used by Universign to sign the webhook

To do so, you must decode the signature header from base64URL to JSON. In the decoded header below, the alg parameter corresponds with the algorithm used to sign and the kid parameter with the public key ID you are looking for.

{"alg":"PS256",
"kid":"scd_78ed7d2bf2a8c4af4a3d3652a89fe8b9f46addb8bc8e7cb69106a6467900f5e6"}

Note: PS256 stands for RSASSA-PSS using SHA-256 and MGF1 with SHA-256, as described in RFC7518 chapter 3.1.

2. Retrieve the public key matching this ID

To do so, you need to access the list of public keys used by Universign, available on https://api.alpha.universign.com/v1/webhooks/jwks.json (Alpha) or https://api.universign.com/v1/webhooks/jwks.json (Production).

3. Reconstruct the signed data

Concatenate the base64URL-encoded header with the base64URL-encoded request body as described in RFC7515. The header being already encoded in base64URL, you need to encode the request body in base64URL.

You may need some useful links:

An example JWS

Message signature or MAC Computation

Message Signature or MAC Validation

4. Verify the obtained signature value with the public key

Using the algorithm retrieved in step 1, and the public key retrieved in step 2, verify that the data obtained in step 3 corresponds to the data signed in the JWS signature.

---

Traces

← Previous

Redirection URLs

Next →