Hubflow webhooks

Summary version. The full documentation (detailed catalog, signature examples) is to be restored from the original webhooks.html file.

Get notified in real time of what happens in your workspace (deposit created, file received, recipient done) without polling the API.

1. How it works

You register a URL and the list of events you care about. As soon as one of these events occurs, Hubflow sends a signed JSON POST to your URL. Delivery is best-effort: if your server is unavailable, the action in Hubflow still completes, and the delivery is recorded and retried automatically. Webhooks are isolated per workspace.

2. Create an endpoint

The secret is used to verify the signature: keep it server-side, and rotate it whenever you like.

3. Event format

Each delivery is a POST whose body contains two keys: type (the event type) and data (the object concerned, in the same representation as the public API). When an action involves several objects, data is an array. The delivery context travels in the headers.

4. Event catalog

• Deposits: deposit.created, deposit.completed…
• Documents and recipients: deposit.directory.created, deposit.directory.completed…
• Files: upload.created, upload.refused…
• Sends: send.signed…

5. Verify the signature

Each request is signed with HMAC-SHA256 using the endpoint’s secret. Recompute the signature over the raw body and compare it with the one in the header before processing the event.

6. Retries and deactivation

A 2xx response within 5 seconds counts as a success. Otherwise, the delivery is retried on an increasing schedule; an endpoint that keeps failing is deactivated automatically.

7. Best practices

Respond immediately and process the event in the background. Make your processing idempotent: the same event may arrive twice.