Configuración

Add an endpoint

Each endpoint receives only the events you choose.

1. Open Webhooks

   Go to Settings, open Advanced, choose Webhooks and click New address.

2. Enter where to send

   Under Where to send alerts paste the Web address (it must start with https) and, optionally, a name or note. Keep Send alerts to this address checked.

3. Choose what to send

   Under What to send check the events you care about or use Select all.

4. Save and copy the signing key

   Click Save address. Save your signing key appears (it starts with whsec_): copy it into your system.

5. Send a test

   Use Send test to receive a test.webhook notification and confirm your system responds.

Available events

Events are grouped by module. Some examples:

• Payments and payment links: payment.succeeded, payment.failed, payment_link.paid.
• Invoices and subscriptions: invoice.paid, subscription.canceled.
• Customers and leads: customer.created, lead.converted.
• Conversations: conversation.assigned, conversation.message.received.
• CRM, follow-ups and flows: deal.won, follow_up.completed, flow_run.completed.

Verify the signature

Every notification includes the X-Recaudo-Signature header with the timestamp (t) and an HMAC-SHA256 signature (v1) of t.body made with your signing key. Compute it yourself and compare before trusting the notification:

X-Recaudo-Signature: t=1760000000,v1=5f2b9c...
X-Recaudo-Event-Id: 9b1d2c3e-...
X-Recaudo-Event-Type: payment.succeeded

<?php
$secret  = getenv('RECAUDO_WEBHOOK_SECRET'); // whsec_...
$payload = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_RECAUDO_SIGNATURE'] ?? '';

parse_str(str_replace(',', '&', $header), $parts); // t=...&v1=...
$expected = hash_hmac('sha256', $parts['t'] . '.' . $payload, $secret);

if (! hash_equals($expected, $parts['v1'] ?? '') || abs(time() - (int) $parts['t']) > 300) {
    http_response_code(400);
    exit;
}

$event = json_decode($payload, true);
http_response_code(200);

const crypto = require('crypto');

// Usa el cuerpo crudo (raw body), no el JSON ya interpretado
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 || ''));
}

The structure of each event is in the API webhooks reference.

Review deliveries and resend

Your system must reply with a 2xx code. If it does not respond or fails, Recaudo retries up to 5 times with increasingly longer waits.

1. Open the details

   In the endpoint list click View details.

2. Check Recent deliveries

   Each delivery shows as Received, Failed or Pending, with the attempt number, the data sent and your system’s response.

3. Resend if needed

   Once you fix the problem in your system, use Resend on the failed delivery.

Next steps