Webhooks

Webhooks notify your application when an event happens in Raims, such as a charge payment or a completed refund. Register the address that will receive these notifications and select the events your system uses.

The API lets you manage the same registrations shown in the Dashboard. To check sending results, use Webhook deliveries.

Complete your first integration

1. Prepare the receiver to validate the signature and accept the event before processing it.
2. Query the event types and select those your application will handle.
3. Register the destination in Sandbox with is_active: false. Keep the returned id and configure secret_key on the receiver's server.
4. Activate the registration, request a test and query the returned delivery. Also check receipt in your application's logs.
5. Use Simulation to generate the financial events your system needs to handle. Check the expected updates and duplicate handling.

The technical event checks the path to the receiver and the signature. Financial tests check your application's response to events such as charge.paid. When preparing Production, use that environment's key, registration and secret.

Register a destination

Before creating a webhook, prepare an HTTPS URL that accepts POST with JSON. Use a domain controlled by your company, with DNS that resolves to a public IPv4 address, on the default port 443. The address cannot be localhost or a direct IP address, or contain a username or password.

Provide a name that identifies the system and its purpose, the URL and the events you want to receive. Keep the id to manage the registration and secret_key to validate the signature. Later queries do not return the secret.

The registration starts active. If the receiver is not ready yet, use is_active: false and activate it later with an update. The same URL cannot be registered twice for the key's company and environment.

The receiver must validate each signature, recognize repeated deliveries and respond within the sending timeout. Follow Receive and validate events to implement this handling. If you restrict sources, allow the official Raims IPs.

Select events

List event types to get the codes available for registration. Provide these codes in events and keep at least one selected. Subscribing to an event does not create an occurrence; the notification depends on the corresponding change.

Select only the events your system needs to process. The technical event webhook.test is sent by the test command and is not part of the registration's event selection.

Query and change settings

List webhooks or query a registration by its id. Queries return the destination's settings and status, without the signing secret.

To update the registration, send only the fields you want to change, with at least one field in the request. Omitting a field keeps its current value. Changing the name, URL or events keeps the identifier and secret. Submitted fields must keep a valid value: null, empty names or URLs and an empty event list do not clear the settings.

URL and event changes apply to subsequent event selections and sending attempts. Requests already authorized or in progress may finish with the previous settings. Adding a type may include earlier events that were still waiting to be prepared; the change does not resend deliveries that have ended. Old events that remain selected may be kept or removed, but can only be added again if they are in the current catalog.

Check destination health

Check webhook health to find out whether a failure episode is recorded. The response includes the available times for the episode's first and last failures, the last success and the update to this information.

While the status is failing, failure_duration_seconds reports how long ago the episode started. Failure times refer to the moment their result was recorded; they are not the event's creation date. A delivery accepted with HTTP 2xx ends the episode. Deactivation also ends it, so a deactivated destination may have no failure times.

The information comes from sending attempts and may appear with a delay. observed_at reports the latest available update. The query does not test the URL or continuously monitor its availability. Use the receipt test when you need to check a new request; its result does not change the recorded health status.

Pause and resume the queue

Pause the queue before maintaining your receiver. Send is_paused: true for an active webhook. Raims keeps pending deliveries and includes new selected events, but does not start sending them while the pause is active. An already authorized request may finish.

A pause does not freeze or extend deadlines: financial deliveries remain limited to 72 hours in Production and four hours in Sandbox. A delivery whose deadline expires during the pause will not be sent when the queue resumes.

After fixing or updating the receiver, send is_paused: false to the same endpoint. Resuming releases deliveries that are still valid, according to the existing sending limits. It does not guarantee immediate sending, a specific order or recovery of deliveries that have ended.

Configuration queries report is_paused and paused_at. Pausing or resuming ends the previous failure episode. This does not confirm that the receiver has recovered; check the attempts after resuming. The pause is separate from is_active: the registration stays active and keeps its settings.

The technical test can be requested during the pause to check the receiver before resuming the queue. It keeps one HTTP attempt and a five-minute deadline, without changing the registration's failure status.

Deactivate and reactivate

Use is_active: false in the update to deactivate the destination and is_active: true to reactivate it. The registration, secret and event selection are preserved.

Deactivation prevents new sends. A pending delivery ends if its next attempt finds the destination deactivated. If reactivation happens first, the delivery may continue within the original deadline. Reactivation does not resend the history or recover deliveries that have ended.

Failures do not pause or deactivate the destination automatically. Raims keeps trying each delivery within its environment's limits. Changing the name, URL, events or secret does not reactivate a manually deactivated registration.

For maintenance that preserves deliveries still within their deadlines, use Pause and resume the queue.

If the queue is paused, reactivating the registration keeps that pause. Resume the queue separately when the receiver is ready.

disabled_reason: manual identifies manual deactivation. Registrations previously deactivated because of failures may keep continuous_failure; check and reactivate them when the receiver is ready. When the webhook is active, this field is null.

Rotate the secret

Request rotation when you need to replace the signing secret. The webhook identifier stays the same. Keep the new secret_key and update the receiver. Configuration queries cannot retrieve this value. Prepare secure storage before requesting rotation.

The transition period lets you receive signatures from both the new and previous secrets while your application is updated. By default, it lasts 24 hours. Use grace_period_seconds: 0 if exposure is suspected or if you need to replace the secret immediately. New sends then use only the new secret as soon as rotation is confirmed. If a transition is active, it ends and both previous secrets are replaced. Requests already authorized or in progress may still arrive with a previous signature. Remove the old secrets from the receiver's configuration so they are no longer accepted.

During the transition, repeating rotation with a period greater than zero returns the same new secret and the same deadline, without extending it. Check previous_secret_expires_at and accept any valid v1 signature, as described in signature validation.

In the Dashboard, rotation always replaces the secret immediately. Choosing a transition period remains available through the API.

Test receipt

Send a test event to an active webhook. The request has no body and returns event_id and delivery_id for follow-up. Acceptance of the request does not confirm that the receiver received it.

The event has type: webhook.test, data.object: webhook and data.id containing the registration's identifier. It uses the webhook's URL and signature and makes a real HTTPS request. It does not create or change charges, payments, refunds or balances.

The test makes one HTTP attempt, with up to five minutes to send. If it fails, fix the receiver before requesting another test. This test's result does not change the failure count or trigger automatic deactivation of the registration.

Each new test request creates another event. To test again, use this same endpoint; webhook.test events cannot be resent through the deliveries resource.

To check financial event handling, use Simulation with a Sandbox key. Keep the effects of these tests separate from your application's production data.

Delete a destination

Delete the webhook when it is no longer used. Deletion prevents new sends to that registration. Requests already authorized or in progress may still finish.

First check whether any system depends on the destination. To stop receipt while keeping the settings, deactivate the registration. Deliveries and attempts remain available for 30 days from the creation of each delivery, but cannot be resent to a deleted registration.

Company and environment

All requests require an API key. The company and environment come from that key: a Sandbox key manages only Sandbox webhooks, and a Production key manages only Production webhooks. This documentation's console accepts only Sandbox keys.

Integration requests use key authentication. Permissions and identity confirmations requested by the Dashboard belong to actions performed in that interface.

Sandbox sends real HTTPS requests. Use a separate test destination and protect the secret on your application's server. Never send it to support or include it in screenshots, URLs or logs.