Webhook events

An event records a change in Raims, such as a charge payment. It has its own identifier, separate from delivery and attempt IDs. Use this query when you have the ID received in the webhook body or need to find events for a charge.

Find an event

List events for the company and environment of the key. You can filter by type, resource and creation period. Use resource_id with the public resource identifier, such as ch_ for a charge or rf_ for a refund. This field does not accept an event or delivery ID.

created_gte and created_lte are UTC Unix seconds with inclusive limits. The list shows the most recent events first. Start without a cursor, process list and copy page.next_after to after while page.has_next is true. Keep the same filters. To go back, use page.previous_before in before, without combining the two cursors. See Listing and pagination.

Each item includes the event ID, type, creation time and related resource. A manual resend keeps the same event and does not create another occurrence in the list. The webhook.test test creates an event for the webhook being tested.

Query the original content

Use Retrieve an event with the event UUID. In addition to the list data, the response includes payload, a string containing the original JSON. Parse this string as JSON when you need to read its fields. The query does not send the event to your receiver.

The query returns created_at in UTC Unix seconds. Inside payload, the original created_at remains in ISO 8601. The content records the event at that moment; query the corresponding resource to check its current state.

The content may include integration data. Restrict access to authorized people and systems, and do not send it to support with sensitive information. To validate notifications received over HTTP, use the webhook signature.

Find deliveries for the event

Use the event_id filter in List deliveries to find deliveries for the same event, including manual resends still available in the history. Each destination and resend has its own delivery_id.

The existence of an event does not confirm delivery. It may have no selected destination, or its delivery may still be waiting. An HTTP 2xx response in an attempt confirms only acceptance by the receiver, not subsequent processing in the destination system.

Send to a webhook

Use Send an event to a webhook with event_id in the path and webhook_id in the body. You can choose a destination from the same company and environment, even if it has no previous delivery for this event.

The event must have been created no more than 15 days ago, with its original body available. The webhook must be active and select the event type at the time of the request. The 30-day query period does not extend this eligibility. webhook.test events require another test.

The 202 response returns the original event and the new delivery identifier. Query that delivery to track the result. The delivery uses the current webhook URL and secrets and preserves the original body, including id and created_at. The request does not change the financial resource or cancel other deliveries for the same event.

If the queue is paused, the new delivery waits for it to resume, with its own deadline of up to 72 hours in Production or four hours in Sandbox. Your receiver must recognize the same event across different deliveries to avoid repeating its effects. After an uncertain API response, query deliveries by event_id before making another request.

History and environment

Events remain available for 30 days from their original creation time. New attempts and resends do not restart this period. A delivery has its own history period, explained in 30-day history.

Queries require an API key from the same company and environment. The console accepts Sandbox only. Records may take a few moments to appear; an empty list does not prove that a financial change did not occur. Query the charge or refund when you need to confirm its state.