Documentation

Webhooks

Receive payment lifecycle updates and validate signatures.

Webhooks notify your systems when checkout sessions change status. Configure a public HTTPS endpoint and verify every request before processing.

Common events

checkout.session.created
checkout.session.completed
checkout.session.expired

Verify signatures

Use your webhook secret to validate the payload signature.

import crypto from 'node:crypto';

const signature = req.headers['stafiel-signature'];
const payload = await req.text();
const expected = crypto
  .createHmac('sha256', process.env.STAFIEL_WEBHOOK_SECRET)
  .update(payload)
  .digest('hex');

if (signature !== expected) {
  throw new Error('Invalid signature');
}

Retries and idempotency

Stafiel retries failed deliveries with exponential backoff. Use idempotency keys in your handler to avoid duplicate processing.