> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rhetoric.law/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

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](https://dashboard.rhetoric.law/).

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:

| Attempt | Backoff period |
| - | - |
| 1 | Immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 8 hours |
| 7 | 24 hours |
| 8 | 48 hours |

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](/api-reference/filers/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](/api-reference/webhooks/filing-submitted)
section of the API reference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.