Receive webhooks when a workflow ends
Get notified in your systems when a workflow run finishes, fails or is stopped, and verify the signature of the deliveries.
Webhooks notify your systems when a workflow run ends. Upsellr then sends a request to the address of your choice. They are included in the Enterprise plan.
The events
| Event | When it is emitted |
|---|---|
| workflow.run.completed | A run finishes successfully |
| workflow.run.failed | A run fails |
| workflow.run.stopped | A user stops a run |
Each delivery contains the full representation of the run, in the same format as the public API. The Event catalogue tab describes this format.
Add an endpoint
- Open the account menu, then Manage and API & webhooks.
- In the Endpoints tab, click Add endpoint.
- Fill in a Name and the Endpoint URL. Only public HTTPS addresses are accepted: private networks and redirects are blocked.
- Tick the Events to receive, then save.
- Copy the signing secret. It is shown only once.
An endpoint can be paused, then reactivated. If you lose the secret, click Rotate secret and update your receiver right away.
Verify the signature
Each delivery carries two headers: X-Upsellr-Timestamp, the delivery’s timestamp, and X-Upsellr-Signature, in the form v1= followed by a lowercase hexadecimal digest. The digest is an HMAC-SHA256, computed with the endpoint’s secret, over the timestamp, a period, then the raw body of the request.
Verify the signature on the raw body, before decoding the JSON. Compare signatures in constant time and reject timestamps that are too old.
Deliveries and retries
- Events are sent as JSON, through a POST request. Any 2xx response confirms receipt.
- If it fails, Upsellr retries after 1 minute, 5 minutes, 30 minutes, 4 hours and 24 hours.
- An event can arrive more than once, and the order is not guaranteed: deduplicate by event ID.
The delivery log
The Event deliveries tab lists the deliveries of the last 7 days, with their status, their attempts and their content. For a failed delivery, click Replay failed delivery: the same event goes out again, with the same ID.
Good to know
- Only owners and admins manage endpoints and replay deliveries.
- Deleting an endpoint cancels its pending deliveries. Existing logs are kept.