Understand webhook delivery
Every event that Riposte emits goes through the delivery engine. We batch events by endpoint, sign each payload, and retry failures using exponential backoff. Before you create endpoints, ensure your infrastructure can receive HTTPS POST requests and respond within the configured timeout.
Endpoints default to a 30 second timeout. You can shorten this for faster retry feedback loops if your service responds quickly.
Create and verify an endpoint
Use the POST /webhooks/endpoints endpoint to register a delivery destination. Provide a descriptive URL, choose which event types you care about, and optionally generate a signing secret. The response includes the generated identifier that you will use for updates.
Specify event types to reduce noise. Leaving the array empty subscribes the endpoint to every event the platform can emit.
Validate signatures
Each webhook payload includes an X-Riposte-Signature header. Compute an HMAC using the shared secret and compare it with the header to ensure the payload originated from Riposte. Reject requests that fail validation with a non-2xx response so that we retry them.
Include the timestamp header in your signature validation to guard against replay attacks. Reject payloads that are older than five minutes unless you are reprocessing events intentionally.
Handle retries gracefully
When your service is unavailable we retry deliveries using exponential backoff. Make your handler idempotent by storing the deliveryId that arrives with every payload. If you already processed the delivery, return 200 without repeating any work.
Use the webhook delivery logs in the admin UI or query the /events endpoint to monitor delivery outcomes while testing.
Test in development
During local development you can use the webhook tunneler or any HTTPS tunnel to forward payloads to your machine. Configure a development endpoint with a short timeout and a descriptive URL so that you can spot it easily in the dashboard.
Use the PUT endpoint to rotate secrets without downtime. Create a new secret, deploy it to your service, and then deactivate the old one once traffic is flowing.