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

# Webhooks

Charge uses webhooks to notify your application when something happens asynchronously, so your integration can react to changes without polling the API.

<Panel>
  <RequestExample>
    ```http Delivery theme={null}
    POST /webhooks/charge HTTP/1.1
    Host: example.com
    Charge-Signature: t=2026-03-03T14:05:23.789Z,v1=4d0f0d7d8ef1bc5e1a0b7ef5d8a26c2ab6f4fce7e9f1a8d06fd30ac2f39c9b1d
    Content-Type: application/json

    {
        "id": "evt_11R9a6NUWsRmOW3RM41L6nFOS1ekDGHo",
        "object": "event",
        "api_version": "2026-03-01",
        "created": "2026-03-03T14:05:23.789Z",
        "data": {
            "object": {
                "id": "rpt_21R9a6NUWsRmOW3RM41L6nFOS1ekDGHo",
                "object": "report",
                // ...
            },
            // ...
        },
        // ...
        "type": "report.succeeded"
    }
    ```
  </RequestExample>

  <ResponseExample>
    ```http Response theme={null}
    HTTP/1.1 200 OK
    ```
  </ResponseExample>
</Panel>

Each delivery is an HTTPS `POST` request that contains an [Event](/api-reference/events/object) payload. The event includes its `type`, the resource snapshot in `data`, the creation time, whether it was generated in live or test mode, and the `api_version` used to render that payload.

Your endpoint should acknowledge webhook deliveries quickly. Charge treats `200`, `201`, `202`, and `204` as successful responses. If your endpoint does not return one of those statuses in time, Charge retries the delivery according to the retry policy below.

Webhook deliveries must be verified before you trust them. Charge signs each request with the `Charge-Signature` header, and your handler should verify that signature against the endpoint secret using the raw request body, not a re-serialized payload.

Webhook consumers should also be built to handle retries and duplicate deliveries. A delivery can be attempted more than once, so your handler should be idempotent and should not assume that each event ID will only ever be seen once.

You control which events a destination receives through [Webhook Endpoints](/api-reference/webhook_endpoints/object). Each endpoint can subscribe to selected event types, and it can optionally pin `api_version` if one consumer needs to stay on a fixed payload shape during an upgrade.

## Webhook payloads

Charge sends an [Event](/api-reference/events/object) payload to your endpoint for each event type you subscribe to.

The table below shows the event types you can receive today.

## Supported event types

| Event type         | Payload object                                    | Description                                                             |
| ------------------ | ------------------------------------------------- | ----------------------------------------------------------------------- |
| `charge.succeeded` | [Transaction](/api-reference/transactions/object) | Sent when a charging transaction has been successfully finalized.       |
| `report.succeeded` | [Report](/api-reference/reports/object)           | Sent when a report run completes successfully and is ready to retrieve. |

## In practice

* Verify the `Charge-Signature` header before trusting the payload.
* Return a `2xx` status only after your handler has accepted the event.
* Store event IDs if you want deduplication on your side.