Skip to main content
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"
}

HTTP/1.1 200 OK
Charge uses webhooks to notify your application when something happens asynchronously, so your integration can react to changes without polling the API. Each delivery is an HTTPS POST request that contains an Event 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. 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 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 typePayload objectDescription
charge.succeededTransactionSent when a charging transaction has been successfully finalized.
report.succeededReportSent 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.