Configure a webhook endpoint

This guide builds a Node.js receiver, registers it, and processes Arrota events safely.

1. Build the receiver

The receiver must read the raw body, verify the signature, respond quickly and then process the event. This example uses Node's built-in http module and the verifyArrotaWebhook function from Verify signatures.

import http from "node:http";
import { verifyArrotaWebhook } from "./verify-arrota-webhook.js";

const processed = new Set(); // Use a database in production.

http.createServer((req, res) => {
  if (req.method !== "POST" || req.url !== "/webhooks/arrota") {
    res.writeHead(404).end();
    return;
  }
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    const rawBody = Buffer.concat(chunks);
    const event = verifyArrotaWebhook(rawBody, req.headers["x-arrota-signature"], process.env.ARROTA_WEBHOOK_SECRET);
    if (!event) {
      res.writeHead(400).end();
      return;
    }
    res.writeHead(200).end(); // Answer first; work afterwards.

    const deliveryId = req.headers["x-arrota-delivery"];
    if (processed.has(deliveryId)) return;
    processed.add(deliveryId);
    handleEvent(event);
  });
}).listen(3000);

function handleEvent({ event, data }) {
  if (event === "credential.claimed") markDelivered(data.document_id);
  if (event === "credential.revoked") markRevoked(data.document_id, data.reason);
}

markDelivered and markRevoked stand for your own code. Make them idempotent: a manual retry arrives with a new delivery ID.

2. Deploy it on HTTPS

Arrota delivers only to https URLs on a public host name. The endpoint must answer within 10 seconds and must not redirect.

3. Register the endpoint

1. In your issuer dashboard, open Settings, then API & Webhooks.
2. Select Add a webhook.
3. Enter your endpoint URL, for example https://integrations.example.com/webhooks/arrota.
4. Choose the events to receive. See Webhook events.
5. Copy the signing secret into your receiver's configuration, for example as ARROTA_WEBHOOK_SECRET. It is shown once.

4. Test it

Issue a credential to trigger credential.issued, or use an existing event: Recent deliveries shows each delivery's status and response code, and Retry sends one again. Deliveries usually arrive within a few minutes.

5. Keep it healthy

• Watch Recent deliveries for failures. After three failed attempts a delivery stops retrying.
• An endpoint whose 10 most recent deliveries all fail is paused. Fix it, then select Resume.
• Rotate the secret if it may have leaked, and update your receiver straight away. See Retries and replay.