Guides
Receiving webhooks
Receive events on your server and verify that Abuna sent them.
Webhooks let your server react when something happens in your app, such as a paid invoice or a canceled subscription. Abuna sends an HTTPS POST to your webhook URL, signed with your signing secret, so you can check that it came from Abuna.
Add your webhook URL
In the dashboard, open Webhooks and set the Webhook URL. Only a team owner can change it, and only from the dashboard. A secret key can't point your webhooks somewhere else.
Test mode and Live mode each have their own webhook URL and signing secret. A new Test app doesn't copy the Live URL, so Test events never reach a server meant for real customers.
The webhook URL must:
- Use
https. - Have a host, and no username or password in it.
- Not point at
localhost, or at a private, loopback, link-local or carrier-grade NAT address. This holds for every request and every redirect, not only for the URL you save.
To receive events on your own machine, expose it through a public HTTPS tunnel and use that URL. The Quickstart has a command for one.
Choose your events
Your webhook URL receives only the event types you choose. When you add it in the dashboard, Recommended is already selected. To change the choice later, a team owner opens Webhooks, edits Events, and keeps Recommended or picks events one by one.
Recommended holds the events a standard integration handles:
session.completed,session.expiredsubscription.created,subscription.trial_ending,subscription.paid,subscription.renewed,subscription.past_due,subscription.recovered,subscription.canceled,subscription.updatedinvoice.created,invoice.paid,invoice.payment_failedcustomer.updated,customer.deleted
What you can rely on:
- Every event is kept in your app's event list, whether or not your URL receives it. See Catch up on missed events.
- The test event always reaches your URL, whatever you chose.
- A new choice applies to events from then on. Events that happened before it aren't sent.
- When Abuna adds an event type, your URL doesn't receive it until you choose it.
- A webhook URL added before 10 October 2026 receives every event type that existed on that date, until you change its events.
webhook_events on the app object lists the event types your URL receives. GET/v1/event-types lists every event type you can choose, with recommended set on the ones in Recommended. It needs no key.
curl https://api.abuna.app/v1/event-types{
"items": [
{ "type": "session.completed", "recommended": true },
{ "type": "session.expired", "recommended": true },
{ "type": "subscription.created", "recommended": true },
{ "type": "subscription.trial_ending", "recommended": true },
{ "type": "subscription.paid", "recommended": true },
{ "type": "subscription.renewed", "recommended": true },
{ "type": "subscription.past_due", "recommended": true },
{ "type": "subscription.recovered", "recommended": true },
{ "type": "subscription.canceled", "recommended": true },
{ "type": "subscription.updated", "recommended": true },
{ "type": "invoice.created", "recommended": true },
{ "type": "invoice.paid", "recommended": true },
{ "type": "invoice.payment_failed", "recommended": true },
{ "type": "customer.updated", "recommended": true },
{ "type": "customer.deleted", "recommended": true },
{ "type": "customer.updates_changed", "recommended": false },
{ "type": "plan_offer.created", "recommended": false },
{ "type": "plan_offer.confirmed", "recommended": false },
{ "type": "plan_offer.canceled", "recommended": false },
{ "type": "plan_offer.expired", "recommended": false },
{ "type": "price_change.scheduled", "recommended": false },
{ "type": "price_change.canceled", "recommended": false },
{ "type": "price_change.applied", "recommended": false }
],
"next_cursor": null
}Get your signing secret
Abuna shows each signing secret once: when you create the app, and when you rotate the secret. A Test secret looks like whsec_test_... and a Live one like whsec_live_.... Store it on your server, next to your secret key.
What Abuna sends
Each delivery is a JSON body with these headers:
X-Abuna-Event: the event type, likeinvoice.paid.X-Abuna-Delivery: the ID of this delivery. It stays the same when a failed delivery is sent again. A redelivery gets a new one.X-Abuna-Environment:testorlive.X-Abuna-Signature: when Abuna signed the request, and the signature. See Verify the signature.
The body always has the same five fields. id is the event's ID. data depends on the type. The mode is in the body as well as the header, because only the body is signed.
{
"created_at": 1794780106,
"data": {
"amount": 5000,
"coupon_id": null,
"credit": 0,
"currency": "XAF",
"discount": 0,
"invoice_id": "OG3ZsOC7",
"invoice_number": "ACME-000001",
"kind": "period",
"metadata": {
"user_id": "42"
},
"paid_at": 1794780106,
"payment": {
"amount": 5000,
"app_id": "qhf83tDc",
"created_at": 1794780106,
"currency": "XAF",
"driver": "sandbox",
"exchange_margin_bps": null,
"exchange_rate": null,
"exchange_rate_at": null,
"fee": 100,
"id": "tGfwt5dd",
"marked_by_api_key_id": null,
"marked_by_user_id": null,
"message": null,
"method_label": "Successful payment (test)",
"net": null,
"note": null,
"original_amount": 5000,
"original_currency": "XAF",
"period_id": "0kYPFwxJ",
"provider": "test",
"provider_reference": "test_ff6aaf0182bd3f1148bd",
"session_id": null,
"status": "succeeded"
},
"period_end": 1797372106,
"period_id": "0kYPFwxJ",
"period_start": 1794780106,
"promotion_code_id": null,
"subscription": {
"activated_at": 1794780106,
"app_id": "qhf83tDc",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"created_at": 1794780106,
"current_period_end": 1797372106,
"current_period_start": 1794780106,
"customer_id": "GzeUZeSV",
"discount": null,
"ended_reason": null,
"id": "wTiODxvH",
"manage_token": "ac78d36db5c13e5f1bcbb67ece2ee29137a0",
"metadata": {
"user_id": "42"
},
"price_id": "IaFQHLTL",
"starts_at": 1794780106,
"status": "active",
"trial_ends_at": null
},
"subscription_id": "wTiODxvH"
},
"environment": "test",
"id": "01M7GKP458FZEMMQQ7VM7J4QK4",
"type": "invoice.paid"
}Verify the signature
X-Abuna-Signature holds comma-separated pairs. t is when Abuna signed the request, in Unix seconds. Each v1 is a hex HMAC-SHA256, keyed by your signing secret, of t, a dot, and the raw body: "<t>.<raw body>".
X-Abuna-Signature: t=1727600000,v1=5f2b8c1e9a4d7f3b6e0c8a2d5f9b1e4c7a3d6f0b8e2c5a9d1f4b7e3c6a0d8f2bFor every request:
- Read the raw body, as bytes, before you parse it.
- Split the header on commas, and each pair on the first
=. Keeptand everyv1. - If
tis more than 300 seconds before or after your server's clock, answer400. This stops someone from replaying an old request. - Compute the HMAC-SHA256 of
t, a., and the raw body with your signing secret, and hex-encode it. - Compare the result with each
v1, using a constant-time comparison. Accept the request if any one matches. - If none matches, answer
400and ignore the event.
The header usually has one v1. While a secret rotation overlaps, it has two: one made with the new secret and one with the old. Accepting any match keeps your server working whichever secret your server holds. Ignore pairs you don't know, so a new signature scheme added later doesn't break you.
import crypto from "node:crypto";
import http from "node:http";
// header is "t=1727600000,v1=<hex>", with a second v1 while a secret rotation overlaps.
function verifyAbunaSignature(rawBody, header, secret) {
const pairs = (header ?? "").split(",").map((part) => part.split("="));
const timestamp = pairs.find(([key]) => key === "t")?.[1] ?? "";
if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = crypto.createHmac("sha256", secret).update(timestamp + ".").update(rawBody).digest();
return pairs.some(([key, value]) => {
const received = Buffer.from(key === "v1" ? value ?? "" : "", "hex");
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
http
.createServer((req, res) => {
const chunks = [];
req.on("data", (chunk) => chunks.push(chunk));
req.on("end", async () => {
const rawBody = Buffer.concat(chunks);
if (!verifyAbunaSignature(rawBody, req.headers["x-abuna-signature"], process.env.ABUNA_WEBHOOK_SECRET)) {
res.writeHead(400).end();
return;
}
const event = JSON.parse(rawBody);
// Save the event before you answer, then handle it in the background.
try {
await saveEvent(event);
} catch {
res.writeHead(500).end();
return;
}
res.writeHead(200).end();
});
})
.listen(3000);Get the raw body in your framework
In Express, express.json() replaces the body with parsed JSON. Use express.raw({ type: "application/json" }) on the webhook route, so req.body is the bytes Abuna sent.
import express from "express";
const app = express();
// express.raw keeps the bytes. Mount it on the webhook route, before any express.json().
app.post("/webhooks/abuna", express.raw({ type: "application/json" }), async (req, res) => {
if (!verifyAbunaSignature(req.body, req.get("X-Abuna-Signature"), process.env.ABUNA_WEBHOOK_SECRET)) {
return res.sendStatus(400);
}
const event = JSON.parse(req.body);
// Save the event before you answer, then handle it in the background.
try {
await saveEvent(event);
} catch {
return res.sendStatus(500);
}
res.sendStatus(200);
});
app.listen(3000);In Laravel, $request->getContent() returns the raw body. Pass it to the PHP function above.
<?php
// routes/api.php. API routes have no CSRF check, so Abuna's POST reaches the handler.
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
Route::post('/webhooks/abuna', function (Request $request) {
// getContent() returns the raw body, before Laravel decodes the JSON.
$rawBody = $request->getContent();
if (!verify_abuna_signature($rawBody, $request->header('X-Abuna-Signature', ''), config('services.abuna.webhook_secret'))) {
abort(400);
}
$event = json_decode($rawBody, true);
// Save the event before you answer, then handle it in the background.
save_event($event);
return response()->noContent();
});Respond with a 2xx
A delivery succeeds when your server answers with a 2xx status within 10 seconds. Up to 4 307 or 308 redirects are followed, and each must meet the URL rules above. Any other answer fails, including a 301, 302 or 303 redirect, a timeout or a connection error.
A failed delivery is sent again for about a day, up to 10 attempts in all. If your server is down for less than that, you miss nothing. After that, the delivery is marked failed, and you can redeliver it.
To handle events safely:
- Save the event first, for example in your database, then answer
2xx. After a2xx, Abuna doesn't send that delivery again. If the save fails, answer500, and the delivery comes again later. Do slow work in the background after you answer, so you stay inside the 10 seconds. - Record each event's
idand skip one you've already handled. The same event can arrive more than once. - Don't rely on order. An older event can arrive after a newer one. See Handle events out of order.
Handle events out of order
Event IDs sort in the order the events happened, so compare them as plain strings to tell which came first. Don't use created_at: it is in whole seconds, and the events of one change often share it. For example, a payment produces invoice.paid and subscription.recovered together, in that order. See Event order for each change.
Every event about a subscription carries the whole subscription in data.subscription, as it stands right after that event. You don't need to replay events in order to know a subscription's state:
- Store, for each subscription, the ID of the newest event you applied to it.
- When an event arrives, compare its
idwith the stored one. If it is newer, savedata.subscriptionas the subscription's state and store the new ID. - If it is older, a newer state is already saved. Keep the stored state, and still do any one-off work the event calls for, like a receipt.
Give the customer access while data.subscription.status is trialing, active or past_due, and take it away at canceled. A renewal still unpaid when the paid period ends is past_due until the customer pays it or the days to pay run out.
Event types
session.completed: a customer finished a session.data.typesays which: forcheckout, the first payment went through or a free trial started, anddata.subscription_idis the new subscription.data.metadatais what you passed when you created it.session.expired: a session ran out or you expired it, without completing.subscription.created: a subscription started, withtrialingfor a free trial orpendingwhile waiting for its first payment.subscription.paid: the first payment went through. After a free trial, that is the first invoice. A trial start sendssubscription.createdonly: grant access whiledata.subscription.statusistrialing. Useinvoice.paidto track money collected.subscription.trial_ending: the trial ends soon, at your app's normal renewal reminder lead time. See Free trials.subscription.renewed: the next billing period and its invoice were issued, 3 days before the paid period ends by default. The new period starts on the renewal date.subscription.past_due: the paid period ended and the renewal is unpaid. A renewal paid before the period ends never sends it. The customer keeps access until the subscription ends.subscription.recovered: the unpaid renewal was paid, and the subscription isactiveagain. It also comes when a payment that arrives after a cancel for non-payment brings the subscription back.subscription.updated: a cancel at the end of the paid period was scheduled or undone, the price changed, a downgrade or an upgrade at the next renewal was scheduled or undone, or an upgrade waiting for payment lapsed.data.cancel_atis when it ends, ornull, anddata.cancel_at_period_endistruewhile a cancel is scheduled.data.price_idis the current price, anddata.changesays what changed about the price.data.updated_byismerchantorcustomer.plan_offer.created,plan_offer.confirmed,plan_offer.canceled,plan_offer.expired: a plan change waiting for the customer was created, accepted, withdrawn or replaced, or ran out. A checkout makes one, and emails the customer its link, when a returning customer picks another price of the product they subscribe to.subscription.canceled: the subscription ended, including at the end of the paid period.data.reasonismerchant,customer,non_payment, orcheckout_expired.invoice.created: an invoice was issued for a billing period.data.kindisplan_changefor the first period of an upgrade.invoice.paid: an invoice was paid.data.paymentis the payment, with what the customer was charged in FCFA and the exchange rate when the invoice was in another currency.invoice.payment_failed: a payment on an invoice didn't go through.data.paymentis the payment that failed.price_change.scheduled,price_change.canceled,price_change.applied: a new amount for a price was scheduled, canceled or replaced, or took effect on its day.data.reasononprice_change.canceledismerchantorreplaced.customer.updated: a customer's name, email, phone number, or metadata changed, or their first payment gave them a phone number.data.updated_byismerchantorcustomer.customer.deleted: you deleted a customer. It follows thesubscription.canceledevent of each subscription that ended.data.deleted_byismerchant.customer.updates_changed: a customer's Telegram or WhatsApp status changed, for example when they turned it on or stopped it.data.channelistelegramorwhatsapp,data.statusis the status now anddata.previous_statusthe one before.
Subscription, invoice, and plan offer events carry the subscription's metadata. Session events carry the session's own metadata, not the subscription's. Pass metadata on every session you create so its events can identify your customer. Without it, session events carry {}.
Every event is also kept in your app's event list, even when no webhook URL is set or your URL doesn't receive its type. See Events for each type's data.
Every event whose data has a subscription_id also has data.subscription, the full subscription object as it stands right after the event.
Send a test event
To check your webhook URL, click Send test event in the dashboard, or call POST/v1/apps/{appID}/webhooks/test. Abuna sends one signed ping event right away and tells you how your server answered, whatever events you chose. It goes once, and it isn't saved as an event or a delivery.
curl -X POST https://api.abuna.app/v1/apps/8ddhXCDW/webhooks/test \
-H "Authorization: Bearer sk_test_..."{
"delivered": true,
"response_status": 200,
"error": null
}delivered is true when your server answered 2xx. If no answer came back, response_status is null and error says why. You can send 10 test events per minute. Without a webhook URL, the call returns 422 with code webhook_url_missing.
{
"id": "01J9ZQ8E1F2G3H4J5K6M7N8P9Q",
"type": "ping",
"environment": "test",
"created_at": 1727600000,
"data": {
"message": "A test event sent from the Abuna dashboard."
}
}Redeliver failed events
Once your server is fixed, list failed deliveries with GET/v1/apps/{appID}/webhooks?status=failed, then redeliver each one with POST/v1/apps/{appID}/webhooks/{id}/redeliver. A redelivery sends the same body again, as a new delivery, to your current webhook URL. It's signed with your current secret and sent again on failure like any other.
curl "https://api.abuna.app/v1/apps/8ddhXCDW/webhooks?status=failed&limit=100" \
-H "Authorization: Bearer sk_test_..."
curl -X POST https://api.abuna.app/v1/apps/8ddhXCDW/webhooks/R3vH6sLd/redeliver \
-H "Authorization: Bearer sk_test_..."See Webhook deliveries for the fields on each delivery. To find events your server never handled, whatever their delivery status, page through the event list. See Catch up on missed events.
Rotate the signing secret
If your signing secret leaks, a team owner can click Rotate secret on the Webhooks page. A secret key can't rotate it. Abuna shows the new secret once and signs with it right away.
For the next 24 hours, X-Abuna-Signature carries a second v1, signed with the old secret. Put the new secret on your server within that time. If you rotate again inside the 24 hours, the secret you just replaced becomes the old one, and the one before it stops working.