Webhooks

Webhooks push real-time event notifications to your application, so you can react to payments, disputes and subscription changes the moment they happen.

Create an endpoint

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {  const sig = req.headers['ledgerline-signature'];  let event;  try {    event = ledgerline.webhooks.constructEvent(      req.body,      sig,      process.env.LEDGERLINE_WEBHOOK_SECRET,    );  } catch (err) {    return res.status(400).send(`Webhook Error: ${err.message}`);  }​  switch (event.type) {    case 'payment_intent.succeeded':      fulfilOrder(event.data.object);      break;    default:      console.log(`Unhandled event type ${event.type}`);  }  res.json({ received: true });});

Test locally with the CLI

ledgerline listen --forward-to localhost:4242/webhook
ledgerline trigger payment_intent.succeeded

Best practices

• Verify signatures. Reject any request whose signature doesn't match your endpoint secret.

• Return 2xx quickly. Do slow work in a background job; we time out after 20 seconds.

• Handle duplicates. Events can be delivered more than once — record processed event IDs.

• Don't rely on order. Events may arrive out of sequence.