Webhooks

KetaPay sends events to the endpoints you register on the dashboard’s Developers page or with POST /webhook_endpoints. Most integrations need one endpoint that receives every event: register it without enabled_events and ignore the types you don’t handle.

Events

Event	When
`escrow.funded`	The buyer paid a checkout session; the escrow exists
`checkout_session.expired`	A session ran out of time unpaid
`milestone.delivered`	The seller marked a milestone delivered
`milestone.released`	A milestone was released to the seller
`escrow.completed`	Every milestone is settled
`escrow.refunded`	The escrow ended with everything returned to the buyer
`dispute.opened` / `dispute.resolved`	A dispute started or ended
`dispute.evidence_requested` / `dispute.evidence_submitted`	KetaPay asked for, or got, evidence
`payout.sent` / `payout.failed`	A seller’s payout landed or failed
`refund.sent` / `refund.failed`	A buyer’s refund landed or failed (not sent during the beta)
`chargeback.opened` / `chargeback.closed`	A card chargeback started or ended (not sent during the beta)

Each event’s payload is in the API reference.

Verify the signature

Each delivery is a POST with the event as its JSON body and a signature header:

KetaPay-Signature: t=1791640000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

v1 is the hex HMAC-SHA256 of "{t}.{raw request body}", keyed with the endpoint’s signing secret (whsec_...). The libraries check it for you, against the raw body, in constant time, rejecting timestamps older than 5 minutes:

app.post(
  '/webhooks/ketapay',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    let event
    try {
      event = await ketapay.webhooks.verify(
        req.body,
        req.header('KetaPay-Signature'),
        process.env.KETAPAY_WEBHOOK_SECRET!,
      )
    } catch {
      return res.sendStatus(400)
    }
    if (event.type === 'escrow.funded') {
      // mark the order paid
    }
    res.sendStatus(200)
  },
)

use KetaPay\Webhook;

$event = Webhook::verify(
    file_get_contents('php://input'),
    $_SERVER['HTTP_KETAPAY_SIGNATURE'] ?? '',
    getenv('KETAPAY_WEBHOOK_SECRET'),
);

Laravel verifies every delivery before your listeners run (see Laravel).

Delivery rules

Respond with any 2xx within 10 seconds. Anything else is retried with exponential backoff for 3 days, after which the endpoint is marked failing and its owner is emailed.
Events can arrive more than once and out of order. Deduplicate on id, and fetch the object (GET /escrows/{id}) when you need the current state.
Treat an event as a hint: fetch the object before acting on large amounts.
Send yourself a test event with POST /webhook_endpoints/{id}/test.

Rotating the secret

POST /webhook_endpoints/{id}/rotate_secret issues a new secret. For 24 hours both secrets sign every delivery and the header carries one v1 per secret (t=...,v1=<new>,v1=<old>): accept the request if any v1 matches. In Node, pass both: verify(body, header, [newSecret, oldSecret]).

Get started

Accept payments

Escrow

Customers

After payment

Integrate

Events

Verify the signature

Delivery rules

Rotating the secret

​Events

​Verify the signature

​Delivery rules

​Rotating the secret

Events

Verify the signature

Delivery rules

Rotating the secret