> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convocore.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Agency Events Webhook

> Get client billing, sign-up and admin events from SaaS Mode in your own CRM or log.

# Agency Events Webhook

The agency events webhook sends a signed JSON event to your server when one of your clients pays, a payment fails, a subscription is cancelled, downgraded or ends, a new client signs up, or an admin changes a client.
It covers Stripe Connect billing, Tap billing and externally billed plans.

Set it up in **Agency → SaaS Mode → Events webhook**:

1. Turn on **Send events**.
2. Paste your **Webhook URL**. It must start with `https://` and be reachable from the internet (private and local network addresses are refused).
3. Untick any events you don't want. New events we add later are sent until you untick them.
4. Click **Send test event** to check your endpoint and reveal your **signing secret**.
5. Save the agency settings.

> [!NOTE]
>
> This is the agency-level webhook for SaaS Mode.
> It is separate from the workspace [Events Webhook](https://docs.convocore.app/features/events.md), which sends agent, conversation and lead events.

***

## Events

| Event | When it fires |
| - | - |
| `payment.succeeded` | A client paid: first subscription payment, renewal, upgrade, first charge after a trial, usage bundle (top-up) or extra-usage invoice. |
| `payment.failed` | A client payment failed: a Stripe invoice charge attempt failed, or a Tap renewal could not be charged automatically. |
| `subscription.cancel_scheduled` | A subscription was set to end at the end of the billing period (or on a set date). |
| `subscription.cancel_undone` | A scheduled cancellation was removed, so the subscription keeps renewing. |
| `subscription.downgrade_scheduled` | A move to a cheaper plan was scheduled for a later date. |
| `subscription.ended` | A subscription ended: cancelled, unpaid, a cardless trial ran out, or an externally paid period lapsed. |
| `client.signed_up` | A new client account was created from your sign-up page or from a checkout. |
| `admin.changed` | An admin changed a client or its organization. |

***

## Request format

| Property | Value |
| - | - |
| **HTTP Method** | `POST` |
| **Content Type** | `application/json` |
| **User-Agent** | `AgencyEvents/1.0` |
| **X-Event-Type** | The event name, for example `payment.succeeded` |
| **X-Convocore-Signature** | Hex HMAC-SHA256 of the raw request body, keyed with your signing secret |

Every request has the same envelope:

```json title="Envelope" theme={null}
{
  "event": "payment.succeeded",
  "id": "5f0c1d5e-8f3a-4f0e-9a3c-2b7d1c9e4a10",
  "ts": 1763290000,
  "agencyId": "agency_abc123",
  "data": { }
}
```

| Field | Type | Description |
| - | - | - |
| `event` | string | The event name. |
| `id` | string | A unique id for this delivery. |
| `ts` | number | When the event was sent, in Unix seconds. |
| `agencyId` | string | Your agency id. |
| `data` | object | The event's fields, described below. |

Redirects are not followed, and each request times out after 8 seconds.
Events are delivered once, without retries, so answer with a `2xx` quickly and do any slow work afterwards.

***

## Verifying the signature

Compute the HMAC-SHA256 of the **raw** request body (the exact bytes you received, before parsing the JSON) with your signing secret, and compare it to the `X-Convocore-Signature` header in constant time.

```js title="Node.js (Express)" theme={null}
import crypto from "crypto";
import express from "express";

const app = express();
const SECRET = process.env.AGENCY_EVENTS_SECRET; // whsec_...

app.post("/webhooks/agency", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const given = String(req.headers["x-convocore-signature"] || "");
  const ok =
    given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
  if (!ok) return res.status(401).end();

  const event = JSON.parse(req.body.toString("utf8"));
  res.status(200).end();
  // handle event.event / event.data here
});
```

```python title="Python (Flask)" theme={null}
import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["AGENCY_EVENTS_SECRET"].encode()

@app.post("/webhooks/agency")
def agency_events():
    raw = request.get_data()
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-Convocore-Signature", "")):
        abort(401)
    event = request.get_json()
    return "", 200
```

***

## Common fields

Billing events share these fields in `data`:

| Field | Type | Description |
| - | - | - |
| `orgId` | string | The client's organization id. |
| `orgName` | string \| null | The organization name. |
| `clientEmail` | string \| null | The email of a client user in the organization. |
| `plan` | string \| null | The plan name. |
| `provider` | `"stripe"` \| `"tap"` \| `"external"` | Where the billing runs. |
| `subscriptionId` | string \| null | The subscription id, when there is one. |

### Amounts

`amount` is always in **currency units**, not minor units: `25` means 25.00 USD, `75` means 75.000 BHD and `1000` means 1,000 JPY.
`currency` is the upper-case ISO 4217 code, for example `USD`, `AED` or `BHD`.
Stripe's minor units are converted for you, including zero-decimal currencies (such as JPY and KRW) and three-decimal currencies (BHD, JOD, KWD, OMR and TND).

### Payment kinds

`kind` on `payment.succeeded` and `payment.failed` tells you what the payment was for:

| `kind` | Meaning |
| - | - |
| `subscription` | The first payment of a new subscription. |
| `trial_activated` | The first charge when a trial ends or the client starts the plan early. |
| `upgrade` | A plan or billing-cycle change charged now (prorated on Stripe). |
| `renewal` | A regular renewal at the start of a new billing period. |
| `bundle` | A one-off usage bundle (extra messages or minutes). |
| `overage` | An invoice for usage past the plan's allowance ("Bill extra usage" plans, Stripe only). |
| `other` | Any other invoice on the client's subscription. |

***

## payment.succeeded

Fired once per paid invoice (Stripe) or captured charge (Tap).
Invoices for `0` (a trial start, a 100% coupon) are not payments and are not sent.

| Field | Type | Description |
| - | - | - |
| `kind` | string | See [Payment kinds](#payment-kinds). |
| `amount` | number | Amount paid, in currency units. |
| `currency` | string | Upper-case ISO currency code. |
| `billingCycle` | `"monthly"` \| `"yearly"` \| null | The plan's billing cycle; `null` for bundles and extra usage. |
| `description` | string | What was paid for, for example `Spark (monthly)` or `500 additional messages`. |
| `chargeId` | string \| null | Stripe charge id (`ch_...`) or PaymentIntent id (`pi_...`), or the Tap charge id. |
| `invoiceId` | string | Stripe invoice id (Stripe only). |

```json title="payment.succeeded (Stripe renewal)" theme={null}
{
  "event": "payment.succeeded",
  "id": "5f0c1d5e-8f3a-4f0e-9a3c-2b7d1c9e4a10",
  "ts": 1763290000,
  "agencyId": "agency_abc123",
  "data": {
    "orgId": "org_7Hk2pQ9x",
    "orgName": "Acme Dental",
    "clientEmail": "owner@acmedental.com",
    "kind": "renewal",
    "amount": 49,
    "currency": "USD",
    "plan": "Growth",
    "billingCycle": "monthly",
    "description": "Growth (monthly)",
    "chargeId": "ch_3QabcDEF123",
    "invoiceId": "in_1QabcDEF456",
    "subscriptionId": "sub_1QabcDEF789",
    "provider": "stripe"
  }
}
```

```json title="payment.succeeded (Tap bundle)" theme={null}
{
  "event": "payment.succeeded",
  "id": "a1d6e0a4-1c7b-4b38-9d0f-6f3a2b1c0e9d",
  "ts": 1763290500,
  "agencyId": "agency_abc123",
  "data": {
    "orgId": "org_7Hk2pQ9x",
    "orgName": "Acme Dental",
    "clientEmail": "owner@acmedental.com",
    "kind": "bundle",
    "amount": 12.5,
    "currency": "BHD",
    "plan": "Growth",
    "billingCycle": null,
    "description": "1,000 additional messages",
    "chargeId": "chg_TS02A1234567890",
    "provider": "tap"
  }
}
```

***

## payment.failed

Stripe sends one event per failed charge attempt, so a renewal that Stripe retries can produce several `payment.failed` events with a rising `attemptCount`.
For Tap, it fires once per billing period when the renewal could not be charged automatically; the client's usage is paused and they receive a link to pay.

All `payment.succeeded` fields, plus:

| Field | Type | Description |
| - | - | - |
| `amount` | number | Amount due, in currency units. |
| `failureReason` | string \| null | Why the payment failed, for example `Your card was declined.` |
| `attemptCount` | number \| null | How many charge attempts have been made for this invoice. |
| `nextAttemptAt` | number \| null | When Stripe will retry, in Unix seconds; `null` when no retry is planned. |
| `payUrl` | string \| null | A page where the client can pay the amount due. |

```json title="payment.failed (Stripe)" theme={null}
{
  "event": "payment.failed",
  "id": "0b8c5e2a-3d4f-4a6b-8c9d-1e2f3a4b5c6d",
  "ts": 1763290000,
  "agencyId": "agency_abc123",
  "data": {
    "orgId": "org_7Hk2pQ9x",
    "orgName": "Acme Dental",
    "clientEmail": "owner@acmedental.com",
    "kind": "renewal",
    "amount": 49,
    "currency": "USD",
    "plan": "Growth",
    "billingCycle": "monthly",
    "description": "Growth (monthly)",
    "chargeId": "ch_3QabcDEF999",
    "invoiceId": "in_1QabcDEF456",
    "subscriptionId": "sub_1QabcDEF789",
    "failureReason": "Your card has insufficient funds.",
    "attemptCount": 1,
    "nextAttemptAt": 1763549200,
    "payUrl": "https://invoice.stripe.com/i/acct_123/test_abc",
    "provider": "stripe"
  }
}
```

***

## subscription.cancel\_scheduled and subscription.cancel\_undone

On Stripe these come from the subscription itself, so they fire whoever made the change: the client in their billing page, your team, or the Stripe dashboard.
On Tap they fire when the client cancels or undoes the cancellation in their billing page.

| Field | Type | Description |
| - | - | - |
| `effectiveAt` | number \| null | When the subscription will end, in Unix seconds (`cancel_scheduled` only). |

```json title="subscription.cancel_scheduled" theme={null}
{
  "event": "subscription.cancel_scheduled",
  "id": "9c1b2a3d-4e5f-4a6b-9c8d-7e6f5a4b3c2d",
  "ts": 1763290000,
  "agencyId": "agency_abc123",
  "data": {
    "orgId": "org_7Hk2pQ9x",
    "orgName": "Acme Dental",
    "clientEmail": "owner@acmedental.com",
    "plan": "Growth",
    "effectiveAt": 1765882000,
    "subscriptionId": "sub_1QabcDEF789",
    "provider": "stripe"
  }
}
```

```json title="subscription.cancel_undone" theme={null}
{
  "event": "subscription.cancel_undone",
  "id": "2d3c4b5a-6f7e-4d8c-9b0a-1f2e3d4c5b6a",
  "ts": 1763300000,
  "agencyId": "agency_abc123",
  "data": {
    "orgId": "org_7Hk2pQ9x",
    "orgName": "Acme Dental",
    "clientEmail": "owner@acmedental.com",
    "plan": "Growth",
    "effectiveAt": null,
    "subscriptionId": "sub_1QabcDEF789",
    "provider": "stripe"
  }
}
```

***

## subscription.downgrade\_scheduled

Fired when a client picks a cheaper plan in their billing page (it starts at the next renewal), or when your team schedules a move to a cheaper plan for a client.

| Field | Type | Description |
| - | - | - |
| `plan` | string \| null | The plan the client will move to. |
| `effectiveAt` | number \| null | When the new plan starts, in Unix seconds. |
| `initiatedBy` | `"agency"` | Present when your team scheduled the change. |

```json title="subscription.downgrade_scheduled" theme={null}
{
  "event": "subscription.downgrade_scheduled",
  "id": "7a6b5c4d-3e2f-4a1b-8c9d-0e1f2a3b4c5d",
  "ts": 1763290000,
  "agencyId": "agency_abc123",
  "data": {
    "orgId": "org_7Hk2pQ9x",
    "orgName": "Acme Dental",
    "clientEmail": "owner@acmedental.com",
    "plan": "Starter",
    "effectiveAt": 1765882000,
    "subscriptionId": "sub_1QabcDEF789",
    "provider": "stripe"
  }
}
```

***

## subscription.ended

Fired once when a client's subscription stops.
When a client moves to a new subscription during a plan switch, the replaced subscription does not send this event.

| Field | Type | Description |
| - | - | - |
| `endedAt` | number | When it ended, in Unix seconds. |
| `reason` | string | See the table below. |

| `reason` | Meaning |
| - | - |
| `canceled` | Cancelled now, or a scheduled cancellation took effect. |
| `payment_failed` | Stripe ended it after the payment retries failed. |
| `payment_disputed` | Stripe ended it because of a payment dispute. |
| `trial_ended` | A trial ended without a payment. The client's usage is paused until they pay. |
| `expired` | An externally paid period ended without a renewal. The client's usage is paused until it is renewed. |
| `other` | Any other reason Stripe gives. |

```json title="subscription.ended" theme={null}
{
  "event": "subscription.ended",
  "id": "3e4d5c6b-7a8f-4e9d-8c1b-2a3f4e5d6c7b",
  "ts": 1765882100,
  "agencyId": "agency_abc123",
  "data": {
    "orgId": "org_7Hk2pQ9x",
    "orgName": "Acme Dental",
    "clientEmail": "owner@acmedental.com",
    "plan": "Growth",
    "endedAt": 1765882000,
    "reason": "canceled",
    "subscriptionId": "sub_1QabcDEF789",
    "provider": "stripe"
  }
}
```

***

## client.signed\_up

Fired once when a new client account is created.

| Field | Type | Description |
| - | - | - |
| `orgId` | string | The new organization id. |
| `clientId` | string | The new client user id. |
| `name` | string | The client's name. |
| `email` | string | The client's email, lower-case. |
| `source` | string | `self_signup` (your sign-up page), `checkout` (your pricing embed or plan link) or `invoice_checkout` (a checkout link you emailed). |
| `plan` | string \| null | The plan bought at checkout (checkout sources only). |
| `billingCycle` | `"monthly"` \| `"yearly"` | The billing cycle bought at checkout (checkout sources only). |
| `provider` | `"stripe"` \| `"tap"` | The checkout's payment provider (checkout sources only). |

A returning client who checks out again with the same email does not create a new account, so it does not send `client.signed_up`; you get `payment.succeeded` instead.

```json title="client.signed_up (checkout)" theme={null}
{
  "event": "client.signed_up",
  "id": "6b5a4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
  "ts": 1763290000,
  "agencyId": "agency_abc123",
  "data": {
    "orgId": "org_7Hk2pQ9x",
    "clientId": "cl_4Mn8rT2v",
    "name": "Dana Lee",
    "email": "dana@acmedental.com",
    "source": "checkout",
    "plan": "Growth",
    "billingCycle": "monthly",
    "provider": "stripe"
  }
}
```

```json title="client.signed_up (sign-up page)" theme={null}
{
  "event": "client.signed_up",
  "id": "8d7c6b5a-4f3e-4d2c-9b1a-0f9e8d7c6b5a",
  "ts": 1763290000,
  "agencyId": "agency_abc123",
  "data": {
    "orgId": "org_7Hk2pQ9x",
    "clientId": "cl_4Mn8rT2v",
    "name": "Dana Lee",
    "email": "dana@acmedental.com",
    "source": "self_signup"
  }
}
```

***

## admin.changed

Fired when an admin edits a client user or its organization.

| Field | Type | Description |
| - | - | - |
| `entity` | `"org"` \| `"client"` | What was changed. |
| `entityId` | string | The organization or client id. |
| `entityName` | string \| null | Its name. |
| `changedBy` | string | The email of the person who made the change, or `API`. |
| `fields` | string\[] | The changed fields. |
| `changes` | array | Up to 40 `{ field, before, after }` entries. |

```json title="admin.changed" theme={null}
{
  "event": "admin.changed",
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "ts": 1763290000,
  "agencyId": "agency_abc123",
  "data": {
    "entity": "org",
    "entityId": "org_7Hk2pQ9x",
    "entityName": "Acme Dental",
    "changedBy": "admin@youragency.com",
    "fields": ["name"],
    "changes": [{ "field": "name", "before": "Acme", "after": "Acme Dental" }]
  }
}
```

***

## Test event

**Send test event** posts a sample `payment.succeeded` with `"test": true` in `data`, signed like a real event.
Ignore events with `data.test` set to `true` in production handling.

***

## Best practices

* Verify the signature on every request before trusting it.
* Match payments to your records with `invoiceId` (Stripe) or `chargeId`.
* Answer with a `2xx` within a few seconds; queue slow work.
* Treat unknown `kind`, `reason` and `source` values as "other": new values may be added.
* Ignore fields you don't use: new fields may be added to `data`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.