Webhooks

Ask Magistrate to notify you when specific events happen by passing a webhook_url when you create an envelope.

How to use webhooks

Creating a webhook endpoint is similar to creating any normal endpoint in your application or website. It's a publicly accessible URL where Magistrate can POST JSON payloads. You tell Magistrate what the URL is when you create an envelope by passing the webhook_url attribute. This immediately dispatches a webhook of type webhook_url_verification.

Your URL should return a 2xx status code when it receives a POST request. We recommend that your webhook endpoint quickly return a 2xx status code and process the JSON payload after returning the successful response to Magistrate's webhook request. Magistrate will automatically retry webhooks that receive a 3xx, 4xx, or 5xx response status code. It will retry it every two hours up to three times.

Magistrate will not retry webhooks of type webhook_url_verification, and if that fails (i.e., does not return a 2xx status code), the API call itself will fail with status code 400.

Magistrate does not guarantee that webhooks will arrive in any particular order, so your application should take care to check the occurred_at timestamp of the event.

Shape generally

The exact payload for a webhook depends on the webhook's type. But all webhooks are shaped like this:

{
  "id": "aaa9ad59-33c2-4290-bf66-bab79002b71e",
  "api_version": 1,
  "type": "envelope_signed",
  "occurred_at": "2022-10-10T09:35:41Z",
  "data": {
    ...
  }
}

Check signatures

Magistrate signs the webhooks it sends to your endpoint by including a signature in the Magistrate-Signature header. This allows you to verify that the webhook is authentic. Magistrate generates signatures using a hash-based message authentication code (HMAC) with SHA-256.

Magistrate-Signature:
t=2022-10-10T14:55:03Z,
v1=d53617a93be26024b3e27f9978d3a6ee20d5e2c2284975a97dd8f35ad088f8d3

To verify the signature, follow these steps:

1. Split the value of the Magistrate-Signature header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair. The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature.

2. Generate a signed_payload string by concatenating:

   • The timestamp
   • The character .
   • The JSON payload, i.e., the request body

3. Calculate the expected signature by computing an HMAC with the SHA256 function and taking the hexadecimal digest. The secret key can be obtained in your integration panel. Use the signed_payload string as the message.

4. Compare the expected signature to the signature in the header. If it matches, compute the difference between the current timestamp and the received timestamp and decide if the difference is within your tolerance. The delta should be no more than a couple of seconds.

Here is an example of how to verify the signature in your app:

const signature = req.headers['Magistrate-Signature']
const timestamp = signature.split(",")[0].split("=")[1]
const signed_payload = timestamp + "." + req.body
const hash = crypto.createHmac('sha256', secret).update(signed_payload).digest('hex')

const expected = signature.split(",")[1].split("=")[1]
if (hash === expected) {
  // Request is verified
} else {
  // Request could not be verified
}

Webhook type reference

There are two webhook types. We will be adding additional webhook types in a backwards-compatible way over time.

Webhook type: envelope_signed

{
  "id": "f9c62dca-5a5b-4564-a0a9-cd86bbe7fde0",
  "api_version": 1,
  "type": "envelope_signed",
  "occurred_at": "2022-10-10 10:14:01Z",
  "data": {
    "envelope_id": "891a4c2f-e0d8-4256-ad10-e217f3e6ac12",
    "signature_id": "346d3ab0-677b-421f-8e3e-795de74044ad",
    "envelope_status": "fully_executed"
  }
}

Webhook type: webhook_url_verification

{
  "id": "c0fa00dc-5da0-4bfe-9b46-3a34f729f8cc",
  "api_version": 1,
  "type": "webhook_url_verification",
  "occurred_at": "2022-11-10 12:12:02Z",
  "data": {
    "user_email": "harry@getmagistrate.com"
  }
}