Outgoing Webhooks

Crovver can push subscription lifecycle events to HTTP endpoints you register. When a subscription is created, activated, renewed, or canceled — whether triggered manually from your dashboard or by a payment provider — Crovver signs a JSON payload and POSTs it to every active endpoint you’ve configured.

Setting Up an Endpoint

Go to Developers → Webhooks in your Crovver dashboard
Click + Add Endpoint
Enter your HTTPS URL — e.g. https://api.your-app.com/webhooks/crovver
Copy the signing secret shown — it is displayed only once and cannot be retrieved again

Your endpoint must respond with a 2xx status within 5 seconds. Any other response or a timeout is recorded as a failed delivery.

Event Envelope

Every event shares the same top-level structure:

{
  "id": "a1b2c3d4-e5f6-...",
  "type": "subscription.activated",
  "created_at": "2026-06-07T10:00:00.000Z",
  "org_id": "org_...",
  "data": {
    "id": "sub_...",
    "status": "active",
    "plan_id": "plan_...",
    "billing_mode": "recurring",
    "external_tenant_id": "your_user_id_123",
    "tenant_name": "Acme Corp",
    "plan_name": "Business",
    "product_name": "Acme ATS",
    "product_slug": "acme-ats",
    "current_period_start": "2026-06-07T00:00:00Z",
    "current_period_end": "2026-07-07T00:00:00Z",
    "capacity_units": 5,
    "created_at": "2026-06-01T00:00:00Z",
    "updated_at": "2026-06-07T10:00:00Z"
  }
}

data.external_tenant_id is the ID you provided when creating the tenant — use this to identify the user or workspace in your own system. data.tenant_name is the human-readable name for quick identification.

Every event that names a subscription also carries the plan and product it belongs to, so you never have to resolve a UUID to route the event:

Field	Use
`plan_name`	Human-readable plan, e.g. `Business`
`product_name`	Human-readable product
`product_slug`	Stable machine identifier — key your routing on this, not the display names

If you sell more than one product, product_slug is what disambiguates an event. Two products can define the same credit pool_key, so a credits.refilled naming only the pool is not enough on its own to decide which product’s balance moved.

Events Reference

Event	When it fires
`subscription.created`	A subscription is manually created from the dashboard
`subscription.activated`	A subscription goes live for the first time — a Stripe checkout completes, a redirect-gateway payment is verified (eSewa, Khalti, ConnectIPS), or an invoice is marked paid
`subscription.updated`	Status, billing period, or seat count changes
`subscription.renewed`	A recurring billing cycle payment succeeds and the period advances
`subscription.canceled`	Subscription is canceled by an admin, the tenant, or the payment provider
`subscription.expiring`	A subscription’s period ends within 7 days and it will not auto-renew — see Expiry warnings
`credits.refilled`	A new credit window began on a contract that was already paid for — see Credit balances
`addon.purchased`	An add-on purchase completed and its credits were granted
`webhook.test`	Sent when you click Send Test from the dashboard

When a free trial ends and the first charge succeeds, both subscription.updated (status: trialing → active) and subscription.renewed (payment received) fire in sequence. These represent distinct state changes — handle them independently and use the top-level id to deduplicate if needed.

Redirect-gateway checkouts (eSewa, Khalti, ConnectIPS) verify the payment server-side after the browser returns, then emit subscription.activated with the tenant’s freshly granted credits. If you integrated against these gateways before, note that this event is newly emitted — previously an activation through them produced no webhook at all.

Expiry Warnings

subscription.expiring is an early warning, not a state change: nothing has happened to the subscription yet. It fires for subscriptions that will lapse unless someone acts — the ones that do not auto-renew. A subscription is selected when all of these hold:

current_period_end is in the future but within 7 days
Status is active, trial, pending_cancel or past_due
Billing is manual — or the status is pending_cancel (a provider-billed subscription that was already told to stop)
The plan is not free

Provider-billed subscriptions are otherwise excluded, because Stripe renews them on its own.

{
  "type": "subscription.expiring",
  "data": {
    "id": "sub_...",
    "tenant_id": "...",
    "external_tenant_id": "workspace_123",
    "status": "active",
    "billing_mode": "manual",
    "current_period_end": "2026-08-25T00:00:00.000Z",
    "capacity_units": 5,
    "currency": "NPR",
    "milestone": "expiring",
    "days_until_expiry": 6,
    "plan_name": "Seed Starter",
    "product_name": "Seed ATS",
    "product_slug": "seed-ats",
    "credits": [
      { "pool_key": "exports", "qty_remaining": 500, "qty_granted": 1750 }
    ]
  }
}

days_until_expiry is the real remaining days, so it varies run to run. milestone labels which warning this is; today expiring is the only value, reserved so additional milestones (T-3, T-1) can be added later as deliberate extra sends.

Sent once per subscription per period. The dedupe key is (subscription, period end, channel), so a subscription warned on the first daily run that sees it is never warned again for that period — even though the 7-day window keeps matching it. Renewing and reaching a new period end makes it eligible again.

The credits block tells you what balance is about to lapse alongside the period, which is what makes this event useful in a renewal nudge rather than just a date reminder.

Credit Balances

Every event that names a subscription carries a credits array with the tenant’s per-pool balances, so you can keep your own mirror in sync without an extra API call.

"credits": [
  { "pool_key": "exports", "qty_remaining": 500, "qty_granted": 1750 }
]

Field	Meaning
`qty_remaining`	Live spendable balance right now — this is the field to sync
`qty_granted`	Total ever granted for this pool on the current contract — a running audit total, not this window’s grant

qty_granted is cumulative, so it will usually be much larger than qty_remaining and the two are not meant to reconcile against each other. A pool granting 500 per window shows qty_granted: 1750 and qty_remaining: 500 in its fourth window — 1,750 handed out across the contract’s history, 500 available today. To show “500 of 500 left” in your UI, compare qty_remaining against the plan’s per-period limit, not against qty_granted.

Because qty_remaining is a full snapshot rather than a delta, set your stored balance from it rather than incrementing. A receiver that sets self-corrects after a missed delivery. On addon.purchased, the top-level qty_granted is that one purchase’s delta (“this purchase added 500”), while qty_granted inside credits is the running total.

`credits.refilled`

Recurring subscriptions refill when the provider charges them, and that is already covered by subscription.renewed. But a manually billed contract can be paid for several credit windows up front — a monthly plan prepaid for a year — and those later windows open with no payment and no status change. Nothing else would tell you the credits arrived. credits.refilled is that signal. It fires from a scheduled job at each window boundary:

{
  "type": "credits.refilled",
  "data": {
    "subscription_id": "...",
    "tenant_id": "...",
    "external_tenant_id": "workspace_123",
    "tenant_name": "Slate Consulting",
    "billing_period": 4,
    "current_period_start": "2026-04-28T15:36:25.264Z",
    "current_period_end": "2027-05-28T15:36:25.264Z",
    "reason": "period_refill",
    "credits": [
      { "pool_key": "exports", "qty_remaining": 500, "qty_granted": 1750 }
    ]
  }
}

billing_period is the window ordinal within the contract — window 4 of a prepaid year. current_period_start and current_period_end are the contract bounds, not the window’s; a refill never moves them. It is not sent when the plan defines no credit pools, when a concurrent run already advanced that window, or for provider-billed subscriptions.

Early renewals refill later, not at payment

This is the case most integrations get wrong, so handle it explicitly.

Early renewal
On-time or late renewal

Paid before the current period ends. Crovver extends current_period_end and keeps the original period start, so the contract now spans more credit windows.No credits are granted at payment time. The subscription.renewed you receive carries pre-refill balances — accurate at that instant, but not the post-renewal figure.Each newly paid-for window is granted later, at its real boundary, and arrives as credits.refilled. Sync balances from that event, not from the renewal.

Paid on or after the period end. Crovver moves both period start and end, restarting the window schedule for the renewed contract.Credits refill immediately, before the webhook is dispatched — so subscription.renewed carries post-refill balances and no credits.refilled follows.A late renewal does not back-fill the unpaid gap: one renewal grants one window. Rollover pools still carry their unused balance forward across the lapse.

Webhooks cover every grant, but not consumption — your backend drives that, and POST /api/public/credits/consume returns the new remaining in its response. Write through from there, set from the credits block on events, and read credit balance when you need certainty.

Verifying Signatures

Every request includes an X-Crovver-Signature header. Always verify it before processing the event.

X-Crovver-Signature: sha256=<hmac-hex>
X-Crovver-Event: subscription.activated
User-Agent: Crovver-Webhook/1.0

The signature is HMAC-SHA256 of the raw request body using your endpoint’s signing secret.

import crypto from "crypto";
import express from "express";

const app = express();

// Use raw body middleware — do NOT parse JSON before verifying
app.post(
  "/webhooks/crovver",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.headers["x-crovver-signature"] as string;

    const expected =
      "sha256=" +
      crypto
        .createHmac("sha256", process.env.WEBHOOK_SECRET!)
        .update(req.body) // raw Buffer — not re-serialized JSON
        .digest("hex");

    const valid =
      sig?.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));

    if (!valid) {
      return res.status(401).json({ error: "Invalid signature" });
    }

    const event = JSON.parse(req.body.toString());

    switch (event.type) {
      case "subscription.activated":
        // Grant access for event.data.external_tenant_id
        break;
      case "subscription.renewed":
        // Extend access period
        break;
      case "subscription.canceled":
        // Revoke access
        break;
    }

    // Always respond 200 quickly
    res.status(200).json({ received: true });
  }
);

<?php
$payload = file_get_contents('php://input');
$sigHeader = $_SERVER['HTTP_X_CROVVER_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $_ENV['WEBHOOK_SECRET']);

if (!hash_equals($expected, $sigHeader)) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

$event = json_decode($payload, true);

switch ($event['type']) {
    case 'subscription.activated':
        // Grant access for $event['data']['external_tenant_id']
        break;
    case 'subscription.canceled':
        // Revoke access
        break;
}

http_response_code(200);
echo json_encode(['received' => true]);

Always verify the signature against the raw request body bytes — not a re-serialized version. JSON parsers may reorder keys, which will break the HMAC comparison.

Delivery & Retries

Crovver delivers each event once. If your endpoint is down or returns a non-2xx status, the delivery is recorded as failed. In Developers → Webhooks, click View Deliveries on any endpoint to see:

The full JSON payload that was sent
The HTTP status and response body your server returned
Attempt count and timestamp

Click Retry on any failed delivery to re-fire it with the same id — so your server can safely deduplicate.

Use the top-level id field as an idempotency key. Store processed event IDs and skip duplicates to handle retries safely.

Testing Locally

Use the Send Test button in your dashboard to fire a webhook.test event to any registered endpoint. The delivery and its payload will appear in the View Deliveries log immediately. To receive events on your local machine, expose it with a tunneling tool like ngrok:

ngrok http 3000
# → https://abc123.ngrok-free.app

Register the generated HTTPS URL as your endpoint — e.g. https://abc123.ngrok-free.app/webhooks/crovver — then use Send Test to verify your handler end-to-end before deploying.

Security Notes

Concern	How it’s handled
Signature forgery	HMAC-SHA256 per-endpoint secret — compare with `timingSafeEqual`
Secret exposure	Signing secret shown once at creation, never returned again
Sensitive fields	Provider IDs, admin-only fields, and internal credentials are stripped from all payloads
Delivery errors	Never surface to the API caller — your subscription action always completes regardless

Overview

Core Concepts

Authentication

SDKs

Guides

Outgoing Webhooks

Setting Up an Endpoint

Event Envelope

Events Reference

Expiry Warnings

Credit Balances

`credits.refilled`

Early renewals refill later, not at payment

Verifying Signatures

Delivery & Retries

Testing Locally

Security Notes

​Setting Up an Endpoint

​Event Envelope

​Events Reference

​Expiry Warnings

​Credit Balances

​credits.refilled

​Early renewals refill later, not at payment

​Verifying Signatures

​Delivery & Retries

​Testing Locally

​Security Notes

Setting Up an Endpoint

Event Envelope

Events Reference

Expiry Warnings

Credit Balances

`credits.refilled`

Early renewals refill later, not at payment

Verifying Signatures

Delivery & Retries

Testing Locally

Security Notes