Receive and Verify a Delivery

Risicare signs each request that it sends to a webhook with the secret of the webhook. Your receiver checks the signature before it reads the body. A request with a wrong signature does not come from Risicare, or it is an old request sent again. You add a webhook and get its secret on the Webhooks page.

The headers

Each request carries two headers that the check reads.

The signature is an HMAC-SHA256 in hex. It is made over the text <timestamp>. followed by the raw bytes of the body. The key is the secret of the webhook. The only scheme is v1. A header may hold more name=value parts, and the helpers ignore them.

A check has three steps, and all must pass:

1. Both headers are present and well formed, and the two timestamps are equal.
2. The timestamp is within 300 seconds of the time now. This stops a captured request from being sent again later.
3. The signature that you compute equals the signature in the header. The helpers compare them in constant time.

What the body holds

The body of a prompt event is JSON. A prompt event carries names, hashes, numbers, links, and the note and reason written with the change. It never carries prompt text.

These keys are in the body of a prompt event.

This page does not list the other keys of a prompt event or the body of the other events.

Python

from risicare import verify_webhook_signature, WebhookVerificationError
 
verify_webhook_signature(payload, headers, secret, *, tolerance_s=300)  # returns None

The function returns None when the delivery is good. It raises WebhookVerificationError when a header is missing, the signature is malformed, the two timestamps differ, the timestamp is outside the tolerance, the signature does not match, or payload has another type. The message is safe to write to a log. It never holds the secret or the expected signature. The error is a subclass of Exception, not of ValueError. The function uses only the Python standard library. The Python SDK exports it: from risicare import verify_webhook_signature. See the Python SDK reference.

JavaScript

import { verifyWebhookSignature, WebhookVerificationError } from 'risicare';
 
verifyWebhookSignature(payload, headers, secret, opts?): void

verifyWebhookSignature is an export of the package root. There is no risicare/webhooks subpath. The package also exports DEFAULT_TIMESTAMP_TOLERANCE_S (300).

The function returns nothing when the delivery is good. It throws WebhookVerificationError for the same causes as the Python function. Catch that class and answer 401, and let other errors pass. The function runs on Node 18 or later and uses node:crypto, so it does not run on edge runtimes. It ships in risicare 0.4.0 and later. See Webhook Verification in the JavaScript SDK reference.

import express from 'express';
import { verifyWebhookSignature, WebhookVerificationError } from 'risicare';
 
const app = express();
// express.raw gives the raw bytes. express.json would parse them first.
app.post('/risicare-webhook', express.raw({ type: '*/*' }), (req, res) => {
  try {
    verifyWebhookSignature(req.body, req.headers, process.env.WEBHOOK_SECRET);
  } catch (e) {
    if (e instanceof WebhookVerificationError) {
      return res.status(401).send(e.message);
    }
    throw e;
  }
  const event = JSON.parse(req.body.toString('utf8'));
  // For a prompt event: drop a repeat by skipping an event whose event.event_id you stored.
  res.status(200).end();
});

Test your receiver

1. Add a webhook with the URL of your receiver and one of prompt.label_moved, prompt.version_created or prompt.promotion_requested. Copy the secret into your receiver.
2. Click Send a test event on the row of the webhook.
3. The page reads "Test event sent to" the webhook and "The receiver took it." when your receiver takes the delivery.

A test event is signed like a real event, so it tests the check as well. A URL that points to a private or internal address is refused. See Webhooks.

Next Steps