Guides
Webhooks
Receive signed events when payments, refunds, and checkouts change.
Camel sends an HTTPS POST to your server when something changes: a payment is approved,
a refund settles, a checkout completes. Webhooks are how you learn about results that arrive after your
request, so use them to fulfil orders.
Add an endpoint
Under Webhooks in the dashboard, add the URL of your endpoint and choose its events. Endpoints belong to one environment and only receive that environment's events. The URL must be public HTTPS on port 443.
Camel shows the endpoint's signing secret (whsec_…) once. Store it
with your API key. Rotating it in the dashboard replaces the old secret immediately.
New endpoints subscribe to payment.*. Add checkout.* and refund.*, or * for everything, if you need them.
Events
| Event | Sent when |
|---|---|
payment.<status> | A payment changes status, for example payment.approved, payment.rejected, or payment.refunded. There's one per payment
status. |
refund.<status> | A refund is created or settles: refund.pending, refund.approved, refund.rejected, refund.failed, refund.unknown. |
checkout.created | A checkout is created. |
checkout.completed | A checkout's payment is approved. |
checkout.expired | A checkout ran out of time unpaid. |
checkout.failed checkout.unknown | Creating a direct checkout failed, or its result is uncertain. |
Subscriptions match an exact type, a prefix such as payment.*, or *.
Payload
The body is an event. data.object is the payment, refund, or checkout as the API
returns it. Payment events from the provider also include data.previous_status.
{
"created_at": "2026-11-12T15:04:07.123456+00:00",
"data": {
"object": {
"id": "pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA",
"object": "payment",
"provider": "mercadopago",
"connection_id": "con_01JBX7P8H2D4F6G8J0K2M4N6QR",
"provider_payment_id": "1342345678",
"amount": 1500000,
"currency": "ARS",
"conversion": null,
"usd_amount": 971,
"status": "approved",
"provider_status": "approved",
"description": "Order #1524",
"external_reference": "ORDER-1524",
"payment_method": {
"type": "card",
"brand": "visa",
"last4": "4242"
},
"failure": null,
"metadata": {
"order_id": "1524"
},
"next_action": null,
"created_at": "2026-11-12T15:04:05Z",
"updated_at": "2026-11-12T15:04:07Z"
},
"previous_status": "processing"
},
"id": "evt_01JBX7R5S6T7V8W9X0Y1Z2A3B4",
"type": "payment.approved"
}Content-Type: application/json
User-Agent: CamelPayment-Webhooks/1.0
X-Event-ID: evt_01JBX7R5S6T7V8W9X0Y1Z2A3B4
X-Webhook-ID: del_01JBX7R6A1B2C3D4E5F6G7H8J9
X-Webhook-Signature: t=1762959847,v1=5f8a3c…Verify signatures
Anyone can send a request to your endpoint, so check that it came from Camel before you act on it. X-Webhook-Signature holds a timestamp t and a signature v1: the HMAC-SHA256, in hex, of t, a dot, and the raw request body,
keyed with your signing secret.
- Read the raw body. Parsing and re-serializing the JSON changes the bytes.
- Reject the request if
tis more than five minutes from your clock. - Compute the HMAC and compare it to
v1in constant time.
Responses and retries
Answer with any 2xx within 10 seconds; do slow work after responding. Any other answer,
a timeout, or a redirect counts as a failure, and Camel tries again after 30 seconds, 2 minutes, 10
minutes, 30 minutes, 2 hours, 6 hours, and 12 hours. After 8 attempts the delivery is marked failed.
The dashboard lists every delivery attempt with its response. You can send a delivery again from there; it carries the same event.
Best practices
- Deduplicate. The same event can arrive more than once. Store the event
id(also inX-Event-ID) and skip ones you've handled. - Don't rely on order. Events can arrive out of order. When in doubt, retrieve the resource for its current state.
- Check the amount. Before fulfilling, compare the payment's amount, currency,
and
external_referencewith your order.