Reacting to payments

The mounted webhook route validates the signature, ledgers the event and syncs the billing tables. What it cannot do is grant the thing the customer bought — that is yours, and it has four homes.

They all run the same contract, (event) => void | Promise<void>. They differ in where the code lives and, much more importantly, what happens when it throws.

What actually retries a failed handler

"Retried" is not one thing, and which mechanism catches your throw depends entirely on billing.dispatcher. Worth getting straight, because only one of them survives the process dying.

The route answers 500 when a handler threw. A 2xx promises the gateway it never has to send that delivery again, which over a failed event is the payment lost for good. A rejected delivery — bad signature, unparsable body — stays 400, because redelivering it would fail identically.

Adyen retries a non-2xx for up to 30 days and Efí makes nine attempts; neither starts on a 2xx. The redelivery is cheap, because the ledger claim means only the failed event re-runs — the events in the same delivery that succeeded are already processed and skip.

The four, side by side

The same job — a Pix payment confirmed, credits granted — written four ways.

node ace make:webhook-handler payment.succeeded

import { inject } from '@adonisjs/core'
import type { WebhookEventFor } from '@adonis-agora/payments'
import { DateTime } from 'luxon'
import Order from '#models/order'
import GrantService from '#services/grant_service'

@inject()
export default class PaymentSucceededHandler {
  static readonly eventType = 'payment.succeeded'

  constructor(private grants: GrantService) {}

  async handle(event: WebhookEventFor<'payment.succeeded'>): Promise<void> {
    // Typed from the event type — a `PaymentWebhookData`, no cast.
    const orderId = event.data.externalReference
    if (!orderId) return

    // The inner idempotency guard — see below.
    const updated = await Order.query()
      .where('id', orderId)
      .andWhere('status', 'awaiting_payment')
      .update({ status: 'paid', paidAt: DateTime.now() })

    if (updated[0] === 0) return

    await this.grants.grantFor(orderId)
  }
}

The dispatcher is a separate decision

Which of the four you use decides where the code lives. billing.dispatcher decides what carries the webhook — and therefore whether a retry survives a restart:

billing: { dispatcher: 'durable' }

'auto' degrades silently: an app that meant to run durable and forgot to register its provider falls back to in-process and nothing says so. Name the backend in production. See Production.

node ace durable:work

The inner idempotency guard

The ledger already stops a redelivery of the same event. It does not make your grant idempotent — two different events can legitimately describe the same fact, a reconcile can replay, a second code path can exist.

The guard belongs at the database, as a conditional write:

const updated = await Order.query()
  .where('id', orderId)
  .andWhere('status', 'awaiting_payment')   // ← only possible once
  .update({ status: 'paid', paidAt: DateTime.now() })

if (updated[0] === 0) return   // someone else already claimed it

A read-then-write races itself under concurrent delivery:

// Wrong: two deliveries can both read 'awaiting_payment' before either writes.
const order = await Order.find(orderId)
if (order.status === 'paid') return
order.status = 'paid'
await order.save()

A unique index on the grant works just as well — (order_id, kind) on a credits table, an upsert, anything whose second execution is a no-op at the database.

Choosing

• Grant credits, activate a subscription, anything the customer paid for → folder or billing.handlers, ideally dispatching to a durable workflow. Retried on failure.
• Multi-step, slow, or must survive a deploy → a durable workflow with @OnDiagnostic. Each step checkpointed.
• Receipts, metrics, Slack pings, analytics → a diagnostics subscriber. Cheap, decoupled, and losing one is survivable.
• A chargeback → a handler, and read the deadline off it. payment.dispute_warning, payment.disputed and payment.dispute_closed are ordinary handler events, but the window they carry is on a clock nothing else here runs on. See Disputes.
• A response shape the mounted route cannot produce → your own controller with new WebhookProcessor({ store, driver, handlers }). See Webhooks.

Whatever you pick, keep the handler fast. Webhooks that hold the connection time out, and a timeout means a redelivery — safe, thanks to the ledger, but slow to converge.