Webhooks

PachaPay sends events to your HTTPS endpoint when payments, payouts and refunds change. Register endpoints with POST /webhook-endpoints (see the reference).

Payload

The body is an event object. data is the full object in its state at the time of the event, not only an id.

{
  "id": "evt_0192f3e5",
  "object": "event",
  "type": "payment.succeeded",
  "created_at": "2026-10-16T12:05:00Z",
  "data": { "id": "pay_0192f3a1", "object": "payment", "status": "succeeded", "amount": 100000, "currency": "CLP" }
}

data.object tells you the type: payment, payout, refund or balance.

Events

Group	Events
Payments	payment.created, payment.requires_action, payment.processing, payment.succeeded, payment.failed, payment.expired, payment.canceled, payment.on_hold, payment.partially_paid, payment.overpaid, payment.chargeback
Payouts	payout.created, payout.processing, payout.succeeded, payout.failed, payout.canceled, payout.on_hold, payout.delayed, payout.returned
Refunds	refund.created, refund.processing, refund.succeeded, refund.failed, refund.returned
Balances	balance.updated

New event types can be added without a new API version. Ignore types you do not handle.

Signature

Every delivery has the header:

PachaPay-Signature: t=1760517000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

v1 is HMAC-SHA256(secret, t + "." + raw_body) in hex, where t is the Unix time and raw_body is the exact bytes received.

1. Read the raw body before parsing.
2. Compute the HMAC with your endpoint secret and compare in constant time.
3. Reject events whose t is older than 5 minutes.

During secret rotation the header holds two v1 values. Accept the delivery if either matches. A TypeScript example is in the Quickstart.

Delivery and retries

• Delivery is at least once. Deduplicate by event.id.
• Reply with any 2xx within 10 seconds to acknowledge.
• Events can arrive out of order. Use the event created_at and, when it matters, read the current object with GET.
• On failure the planned retry schedule is: 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, then every 24 hours up to 3 days (about 10 attempts in total).
• After 3 days of failures the event stays available through GET /events and the endpoint is marked failing. After 7 days of failures in a row the endpoint is disabled and the owner is notified.
• Events are kept for 30 days. Use GET /events to recover events your endpoint missed.
• A manual redelivery is available in the dashboard.

Rotating the secret

POST /webhook-endpoints/{endpoint_id}/rotate-secret returns a new secret, shown once. The old secret stays valid for 24 hours, and during that time each delivery carries two v1 signatures.

Endpoint rules

• HTTPS only.
• The secret is returned only when the endpoint is created or rotated.
• A project can have a limited number of active endpoints (planned: 10).