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:- Turn on Send events.
- Paste your Webhook URL. It must start with
https://and be reachable from the internet (private and local network addresses are refused). - Untick any events you don’t want. New events we add later are sent until you untick them.
- Click Send test event to check your endpoint and reveal your signing secret.
- Save the agency settings.
This is the agency-level webhook for SaaS Mode.
It is separate from the workspace Events Webhook, which sends agent, conversation and lead events.
Events
Request format
Every request has the same envelope:
Envelope
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 theX-Convocore-Signature header in constant time.
Node.js (Express)
Python (Flask)
Common fields
Billing events share these fields indata:
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:
payment.succeeded
Fired once per paid invoice (Stripe) or captured charge (Tap). Invoices for0 (a trial start, a 100% coupon) are not payments and are not sent.
payment.succeeded (Stripe renewal)
payment.succeeded (Tap bundle)
payment.failed
Stripe sends one event per failed charge attempt, so a renewal that Stripe retries can produce severalpayment.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:
payment.failed (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.subscription.cancel_scheduled
subscription.cancel_undone
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.subscription.downgrade_scheduled
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.subscription.ended
client.signed_up
Fired once when a new client account is created.
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.
client.signed_up (checkout)
client.signed_up (sign-up page)
admin.changed
Fired when an admin edits a client user or its organization.admin.changed
Test event
Send test event posts a samplepayment.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) orchargeId. - Answer with a
2xxwithin a few seconds; queue slow work. - Treat unknown
kind,reasonandsourcevalues as “other”: new values may be added. - Ignore fields you don’t use: new fields may be added to
data.
