Docs
Search the docs
Find a page in the docs

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

EventSent 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.createdA checkout is created.
checkout.completedA checkout's payment is approved.
checkout.expiredA 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.

payment.approved
{
  "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"
}
Headers
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.

  1. Read the raw body. Parsing and re-serializing the JSON changes the bytes.
  2. Reject the request if t is more than five minutes from your clock.
  3. Compute the HMAC and compare it to v1 in constant time.
import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Read the raw body: the signature covers the exact bytes Camel sent.
app.post('/webhooks/camel', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('X-Webhook-Signature') ?? '';
  const parts = Object.fromEntries(header.split(',').map((part) => part.split('=', 2)));
  const timestamp = Number(parts.t);
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > 300) {
    return res.sendStatus(400);
  }

  const expected = crypto
    .createHmac('sha256', process.env.CAMEL_WEBHOOK_SECRET)
    .update(`${parts.t}.`)
    .update(req.body)
    .digest('hex');
  const valid =
    typeof parts.v1 === 'string' &&
    parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
  if (!valid) return res.sendStatus(400);

  const event = JSON.parse(req.body);
  // Skip events you already handled (event.id), then handle event.type.
  res.sendStatus(200);
});

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 in X-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_reference with your order.