Skip to article

Core concepts

Webhooks

Subscribe to billing events, verify signatures, and handle retries safely.

Webhooks push billing events to your endpoint as they happen. This page is a placeholder for the delivery contract.

Subscribe#

POST/v1/webhooks

Register an endpoint to receive events. The secret is returned once.

{
    "url": "https://example.com/hooks/verlix",
    "events": ["invoice.issued", "payment.failed"]
}

Verify the signature#

Every delivery carries a signature over the raw body. Verify it before you parse the payload.

Verify before you trust

An unverified webhook is an unauthenticated write to your system. Reject any delivery whose signature does not match.

import { verifySignature } from "@verlix/sdk";
 
export async function POST(request: Request) {
    const raw = await request.text();
    const signature = request.headers.get("verlix-signature") ?? "";
    if (!verifySignature(raw, signature, process.env.WEBHOOK_SECRET!)) {
        return new Response("invalid signature", { status: 401 });
    }
    return new Response("ok");
}

Event types#

EventFires when
invoice.issuedAn invoice becomes final
invoice.paidAn invoice is fully paid
payment.failedA payment attempt fails
customer.createdA customer record is created

Handle retries#

  1. Respond quickly

    Return a 2xx within five seconds. Do the real work asynchronously.

  2. Be idempotent

    A delivery may arrive more than once. Key your processing on the event id.

  3. Expect backoff

    Failed deliveries are retried with exponential backoff for up to 24 hours.