Webhooks integration

Webhooks let ArcenPay push real-time billing events to your server. When a subscription renews, a plan changes, or a payment completes, ArcenPay sends a signed HTTP POST to your registered endpoint.

Prerequisites

A publicly accessible HTTPS endpoint that accepts POST requests
Your webhook signing secret from the dashboard (Settings → Webhooks)
@arcenpay/node for signature verification

Registering a webhook endpoint

Go to Settings → Webhooks in the ArcenPay dashboard.
Enter your endpoint URL (e.g., https://api.myapp.com/webhooks/arcenpay).
Copy the signing secret (whsec_...).
Click Enable Webhooks.

Verifying signatures

Every webhook request includes an X-ArcenPay-Signature header with an HMAC-SHA256 hex digest. Always verify this signature before processing the payload:

import { verifyWebhookSignature } from "@arcenpay/node";

export async function POST(request: Request) {
  const rawBody = await request.text();
  const header = request.headers.get("x-arcenpay-signature") ?? "";

  if (!verifyWebhookSignature(rawBody, header, process.env.ARCENPAY_WEBHOOK_SECRET!)) {
    return new Response("Invalid signature", { status: 401 });
  }

  const event = JSON.parse(rawBody);
  await handleEvent(event);
  return new Response("OK", { status: 200 });
}

Pass the raw header value directly — verifyWebhookSignature handles stripping the sha256= prefix internally. Always verify the raw request body before JSON parsing.

Event types

Event	When it fires
`company.created`	A company record was auto-created or identified for your team.
`user.created`	A user record was auto-created or identified for a company.
`company.plan.changed`	A company was assigned to a new plan after activation or an admin update.
`company.plan.cancelled`	A company’s subscription was cancelled or removed.
`subscription.minted`	A new subscription NFT was minted on-chain.
`subscription.renewed`	A subscription successfully renewed for another billing period.
`subscription.auto_renewed`	The renewal service completed an automated renewal.
`subscription.renewal_failed`	An automated renewal attempt failed; the subscription needs attention.
`subscription.cancelled`	A subscription was cancelled through the billing lifecycle.
`invoice.issued`	An invoice was issued to a customer.
`invoice.delivery_failed`	An invoice email could not be delivered to the customer.
`invoice.paid`	An invoice was marked as paid.
`payment_link.created`	A hosted payment link was created from the dashboard or API.
`payment_link.updated`	A hosted payment link was updated, activated, deactivated, or archived.
`checkout.session.created`	A customer opened a hosted checkout link and a payment session was created.
`checkout.session.paid`	A hosted checkout session was paid and verified on-chain.
`credit.low_balance`	A company’s credit balance fell below 20% of its initial grant.

Handling events idempotently

Webhooks may be delivered more than once. Use the event id field to deduplicate:

const processedIds = new Set<string>();

async function handleEvent(event: { id: string; type: string; data: any }) {
  if (processedIds.has(event.id)) return;
  processedIds.add(event.id);

  switch (event.type) {
    case "subscription.minted":
      await activateService(event.data.companyId);
      break;
    case "subscription.renewal_failed":
      await suspendService(event.data.companyId);
      break;
    case "company.plan.cancelled":
      await revokeAccess(event.data.companyId);
      break;
    case "company.plan.changed":
      await updateEntitlements(event.data.companyId);
      break;
  }
}

Retry behavior

ArcenPay retries failed webhook deliveries with exponential backoff. If your endpoint returns a non-2xx status or the request fails, the event is retried up to 5 times with delays of 1 second, 5 seconds, 30 seconds, 5 minutes, and 30 minutes before delivery is abandoned.

Testing webhooks

Send a test event from the dashboard under Settings → Webhooks → Send Test.

Rotating the signing secret

Rotate the webhook secret from Settings → Webhooks → Rotate Secret. The new secret takes effect immediately and signs all subsequent webhooks. If your handler needs time to transition, store the previous secret yourself and accept both signatures during the switchover:

const valid =
  verifyWebhookSignature(rawBody, header, currentSecret) ||
  verifyWebhookSignature(rawBody, header, previousSecret);

Next steps

Webhooks SDK reference — verifyWebhookSignature and error handling
Subscriptions API — the endpoints that trigger webhook events
Authentication — webhook signing secret and credential management

Get started

Core concepts

Guides

Integrations

Webhooks integration

Prerequisites

Registering a webhook endpoint

Verifying signatures

Event types

Handling events idempotently

Retry behavior

Testing webhooks

Rotating the signing secret

Next steps

​Prerequisites

​Registering a webhook endpoint

​Verifying signatures

​Event types

​Handling events idempotently

​Retry behavior

​Testing webhooks

​Rotating the signing secret

​Next steps

Prerequisites

Registering a webhook endpoint

Verifying signatures

Event types

Handling events idempotently

Retry behavior

Testing webhooks

Rotating the signing secret

Next steps