Your payment webhook has a 24-hour cliff. Here's the reconciliation job that catches it.

Every webhook tutorial covers the happy path: verify the signature, return 200, done.

Almost none cover what happens when your endpoint is down for a day.

Most payment platforms retry with exponential back-off, and then they stop. On Atoa's side the documented behaviour is: any response other than HTTP 200 is a failure, we retry with back-off, and if deliveries keep failing for more than 24 hours we stop and email the business owner with the failing URL. That is a sensible design. It also means there is a cliff, and anything that falls off it is only recoverable if you built a second path.

This is the setup I'd build so a bad Friday deploy never turns into a Monday reconciliation fire.

The mental model: a webhook is a hint

Treat the webhook as a doorbell, not the delivery. It tells you "something changed, go and look." The source of truth is the payment record, which you can always read back from the API.

Once you accept that, three design decisions follow.

1. Verify against the raw body, and do it first

Atoa's V2 signing sends X-Atoa-Signature: v1=<hex>, an HMAC-SHA256 over the entire raw request body. The secret looks like whsec_<base64>, and the key is the base64-decoded part after the prefix.

const crypto = require('crypto');

function isValidAtoaSignature(signingSecret, rawBody, headerValue) {
  if (!headerValue || !headerValue.startsWith('v1=')) return false;

  const provided = Buffer.from(headerValue.slice(3), 'hex');
  const key = Buffer.from(signingSecret.slice(signingSecret.indexOf('_') + 1), 'base64');
  const expected = crypto.createHmac('sha256', key).update(rawBody, 'utf8').digest();

  // timingSafeEqual throws on unequal lengths
  if (provided.length !== expected.length) return false;
  return crypto.timingSafeEqual(provided, expected);
}

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const raw = req.body.toString('utf8');
  if (!isValidAtoaSignature(process.env.ATOA_SIGNING_SECRET, raw, req.get('X-Atoa-Signature'))) {
    return res.status(401).send('Invalid signature');
  }
  queue.add('atoa-event', JSON.parse(raw)); // enqueue, don't process
  res.status(200).send('OK');              // ack fast
});

Two things that bite people. Use express.raw, not express.json, because a re-serialised body will not match the signature. And note that the docs describe no timestamp in the header, so there is no built-in replay protection. Do not assume it. You need your own dedupe.

2. Make the handler idempotent on the payment, not the delivery

The payload carries paymentRequestId, orderId, paymentIdempotencyId and a status of COMPLETED, PENDING, FAILED (plus AUTHORIZED and CANCELLED for card). Retries mean you will see the same event more than once, and a PENDING can arrive after you have already acted on a COMPLETED if you are unlucky with ordering.

So I'd key state changes on paymentRequestId and only allow forward transitions:

const RANK = { PENDING: 1, FAILED: 2, COMPLETED: 2 };

async function apply(event) {
  const row = await db.payments.get(event.paymentRequestId);
  if (row && RANK[event.status] <= RANK[row.status]) return; // stale or duplicate
  await db.payments.upsert({ id: event.paymentRequestId, status: event.status });
  if (event.status === 'COMPLETED') await fulfilOrder(event.orderId);
}

A late PENDING can never un-complete an order, and a second COMPLETED is a no-op.

3. Add the sweep, the part most teams skip

This is the piece that makes the cliff irrelevant. Run a job every 10 to 15 minutes that finds payments you created more than N minutes ago and still hold as non-final, then asks the API for their current status and feeds the answer through the same apply() function.

cron('*/10 * * * *', async () => {
  const stale = await db.payments.where({ status: 'PENDING' }).olderThan('10 minutes');
  for (const p of stale) {
    const live = await atoa.getPaymentStatus(p.id); // see docs.atoa.me, Get payment status
    await apply(live);
  }
});

The sweep and the webhook share one code path, so there is nothing new to test and no second definition of "paid." If your endpoint is down for 30 hours, the webhooks stop at 24, and the sweep quietly repairs everything on the next run after you are back.

One caveat: getPaymentStatus here is a thin wrapper I've sketched. Check the exact endpoint and fields in the docs before you copy it.

Setup details worth knowing

• V2 endpoints support multiple event types per endpoint and up to 3 endpoints per event type, each delivered independently. Point one at your app and one at a separate audit or analytics consumer, so one failing does not affect the other.
• Failure tracking on V2 exposes failureCount and lastDeliveredAt. Alert on lastDeliveredAt going stale rather than waiting for the owner email.
• Optional endpoint auth (OAuth 2.0 or Basic Auth) can sit on top of the signature. The docs recommend combining them.
• Test in sandbox with the trigger-test-webhook API, overriding status, amount and orderId to simulate failures. It is sandbox-only; production keys are rejected.
• Rotation is instant. Rotating the signing secret invalidates the old one immediately, and enabling V2 switches every delivery, including the WooCommerce and Magento plugins. Update your env first.

What I'd do, in order

1. Verify on the raw body, enqueue, return 200.
2. Key state on paymentRequestId, forward-only transitions.
3. Ship the sweep before you ship to production, not after the first incident.
4. Alert on lastDeliveredAt.

Webhooks are fast. Reconciliation is correct. You want both.

Try Atoa's sandbox: docs.atoa.me