Setup and Verification

Register an endpointCopy Anchor Link

Create webhook endpoint with:

The response includes the signing secret, shown only once.

Choosing the projectCopy Anchor Link

Endpoints receive the events of one project. By default that is the project of the API key you call with. To manage another project's endpoints, add ?projectId=<project id> to any webhook endpoint request. A key can name its own project, or any of your business's payment-links projects in the same environment. Other projects are managed in the dashboard.

Payment events go to the project the payment belongs to, so register endpoints on your payment-links project to receive them.

To add events to an endpoint, update it rather than registering the same URL again.

recovery.code and recovery.started are managed only in the dashboard, by an owner or admin.

Verify a notificationCopy Anchor Link

Each notification is a POST with these headers:

The signature is the hex HMAC-SHA256 of <timestamp>.<raw body> with your signing secret.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, rawBody, header) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const expected = createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');
  const a = Buffer.from(parts.v1, 'hex');
  const b = Buffer.from(expected, 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

Responding and retriesCopy Anchor Link

Respond quickly with 2xx, then process the event.

Delivery guaranteesCopy Anchor Link

Sample consumerCopy Anchor Link

import express from 'express';

const app = express();

app.post(
  '/webhooks/wallet',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const rawBody = req.body.toString('utf8');
    const signature = req.header('x-signature') ?? '';
    const sentAt = Number(req.header('x-timestamp'));
    const eventId = req.header('x-idempotency-key') ?? '';

    if (!verify(process.env.WEBHOOK_SECRET!, rawBody, signature))
      return res.sendStatus(401);
    if (Math.abs(Date.now() / 1000 - sentAt) > 300) return res.sendStatus(400);
    if (await alreadyProcessed(eventId)) return res.sendStatus(200);

    await saveForProcessing(eventId, JSON.parse(rawBody));
    res.sendStatus(200);
  },
);

verify is the function above. alreadyProcessed and saveForProcessing are your own storage: record the event first, respond, then process it from your store.

ErrorsCopy Anchor Link