Skip to main content

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.
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 the X-Convocore-Signature header in constant time.
Node.js (Express)
Python (Flask)

Common fields

Billing events share these fields in data:

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 for 0 (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 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:
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 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.