Skip to main content
A webhook is a message sent from one application to another when a specific event occurs. Rhetoric sends webhook events to mark different points in the filing lifecycle, such as when a filing is accepted or rejected. Instead of polling the API for status changes, you can register an endpoint, and Rhetoric will send an HTTP request to that endpoint whenever a relevant event occurs.

​
Creating a webhook

You can create and manage webhooks from the Webhooks page in the dashboard.
  1. Select Add endpoint.
  2. Provide the URL that should receive events, and the environment (live or test) the webhook applies to. Events are only sent to webhooks whose environment matches the environment the event occurred in.
  3. Select Create.
Rhetoric generates a secret key for the webhook and displays it once, at creation time. Store this key securely. Rhetoric sends this key as a bearer token in the Authorization header alongside each request; you can use it to verify that a request came from us. If you lose it, delete the webhook and create a new one. Each organization can have at most five webhooks. If you need to notify more than five destinations, consider fanning out events from a single endpoint you control. You can also disable a webhook from the dashboard without deleting it, which pauses delivery until it is enabled again. You can also send a sample event to a webhook at any time using the Test option in the options menu for the webhook, to confirm that your endpoint is reachable and configured correctly before relying on it.

​
Retries

Rhetoric expects your endpoint to respond with a successful HTTP status code (2xx) within five seconds of receiving a request. If a request fails, whether due to a network error, a timeout, or a non-successful status code, Rhetoric retries delivery with the following backoff schedule, for a total of up to eight attempts: If the eighth attempt still fails, Rhetoric stops retrying that event, and no further notice is given. If you suspect an event was dropped, use the list filers and related endpoints to reconcile state directly against the API.

​
Idempotency

Rhetoric delivers events with at-least-once semantics. This means your endpoint may receive the same event more than once, for instance if a request succeeds but the acknowledgment is lost before Rhetoric records it as delivered. Your endpoint should not assume that each event is delivered exactly once. To handle this correctly, use the id field on the event payload to deduplicate: record the IDs of events you have already processed, and skip any event whose ID you have seen before. Because the same underlying occurrence (for example, a specific filing being accepted) may also be reported to you through separate mechanisms, avoid relying solely on the event data to infer whether you have already handled it; the event id is the reliable key.

​
Available events

For a complete list of the events Rhetoric can send, along with the shape of each payload, see the Webhooks section of the API reference.