connector.* events
A project's connectors as they are installed, connected, verified, configured and disconnected: the family every connector answers to.
A project's connectors as they are installed, connected, verified, configured and disconnected: the family every connector answers to.
A project runs on connectors: the platforms it gates access on, sends messages through and takes payments from. Each one the project runs is an installation, and every move in an installation's life is announced here: it is installed (a pending row, no credentials yet), connected (the creator handed the connector its credentials), verified or probed (its state moved), configured (a declared setting changed), disconnected (the credentials wiped, the row kept) and uninstalled (its grants revoked and resources detached, the row still kept). The events name Subscriby ids and the connector key only; a platform's own identifiers, tokens and settings values never travel in a webhook.
Background
Read them together with the API
The installation_id in every payload is the id of the rows the project's installations endpoint lists, and connector is the key of a card in the connector directory. A consumer that keeps a mirror of a project's connectors applies these events to those rows.
Example envelope
{
"id": "evt_01HX...",
"type": "connector.connected",
"created_at": "2026-09-12T10:06:00Z",
"api_version": "2026-05-01",
"project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
"data": {
"connector": "telegram",
"installation_id": "3b8f0c6e-2d41-4a97-9e5f-1c7d6b2a8e40",
"project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
"display_name": "Research Bot",
"handle": "research_bot"
}
}Required ability
Every connector.* event requires project-connector:view on the subscribing token and carries the project's project_id.
Events
connector.installedA connector was installed on a project: a pending installation with no credentials yet.connector.connectedThe creator connected an installation with their credentials; the connector can act for the project now.connector.disconnectedAn installation was disconnected: the connector withdrew it, the credentials were wiped, the row stays.connector.status_changedA probe or a verify moved an installation's state: connected, degraded or revoked.connector.settings_updatedA declared setting of an installation changed: which fields, never their values.connector.uninstalledA connector was uninstalled from a project: its grants revoked, its resources detached, the installation row kept, with the counts of what that touched.connector.doctor_completedThe connector doctor ran on an installation and found something different from the previous run.connector.outage_openedA platform refused a project's live installation (token revoked or regenerated, bot deleted) and the connector entered an outage.connector.outage_closedA connector outage ended: the installation answered again, another one took its place, or the creator uninstalled the connector.connector.outage_compensatedA closed connector outage settled: how many members had time banked, how much each received, and how many invites lost during the outage were re-sent.connector.installed
WEBHOOKA connector was installed on a project: a pending installation with no credentials yet.
When this fires
A creator (or a token) installs a connector on a project: from the Connectors tab, through the install endpoint or the install_connector tool. Installing says "this project runs this connector" and opens the row the Connectors tab shows as pending; connecting, which hands the connector the creator's credentials, is a separate act and fires connector.connected. Installing a connector that is already installed changes nothing and fires nothing; bringing an uninstalled connector back fires this again, the row pending once more with its settings kept.
Caveats
- A second distinct connector on a project needs the owner's
multi_connectorcapability (Growth); the install is refusedCONNECTOR_TIER_REQUIREDand nothing fires. - The first connector's bot flow connects in one step from the dashboard, so an existing project sees
connector.connectedwithout a precedingconnector.installed.
Related events
connector.connected: the credentials handed over.connector.disconnected: the reverse.
Ability to subscribe
A token needs this to subscribe an endpoint to the event.
Header Parameters
t=<unix seconds>,v1=<hex>: the HMAC-SHA256 of "<t>.<raw body>" under the endpoint's secret. Verify it before acting, and refuse a t more than 300 seconds from now. During a secret rotation a v0= signature under the previous secret may precede v1=.
The event's ULID, bare. The envelope's id is the same ULID prefixed evt_, so strip the prefix before comparing. Deduplicate on it: a retry carries the same id.
The event name, the same as the envelope's type.
Always application/json.
Always Subscriby-Webhooks/1.0.
Payload
JSONWhat Subscriby posts to your endpointapplication/json
The signed JSON envelope posted to your endpoint.
The envelope every event is delivered in.
Responses
2XXAny success status
Your endpoint acknowledged the delivery. Any 2xx status within 30 seconds marks it delivered; the response body is ignored.
defaultAny other status
Any other status, a connection failure, or no answer within 30 seconds counts as a failed attempt. The delivery is retried 8 times, after 10 seconds, 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours, 1 day, 3 days; the last failure dead-letters it, and it can be retried from the dashboard or POST /v1/webhook-deliveries/{delivery}/retry. After 20 consecutive failures the endpoint is paused until it is resumed.
connector.connected
WEBHOOKThe creator connected an installation with their credentials; the connector can act for the project now.
When this fires
A creator completes a connector's connect flow on the dashboard: the connector checks the credentials, registers with its platform and the installation turns connected. For the first connector this is the Connect Bot modal, the platform bot's connectivity conversation and a Disaster Recovery bot replacement.
Caveats
- Credentials are never in the payload. Read the installation back with the installation endpoint.
- Reconnecting with new credentials fires this again for the same
installation_id.
Related events
connector.installed: the pending row that preceded it, when the connector installs in two steps.connector.status_changed: the installation's health afterwards.
Ability to subscribe
A token needs this to subscribe an endpoint to the event.
Header Parameters
t=<unix seconds>,v1=<hex>: the HMAC-SHA256 of "<t>.<raw body>" under the endpoint's secret. Verify it before acting, and refuse a t more than 300 seconds from now. During a secret rotation a v0= signature under the previous secret may precede v1=.
The event's ULID, bare. The envelope's id is the same ULID prefixed evt_, so strip the prefix before comparing. Deduplicate on it: a retry carries the same id.
The event name, the same as the envelope's type.
Always application/json.
Always Subscriby-Webhooks/1.0.
Payload
JSONWhat Subscriby posts to your endpointapplication/json
The signed JSON envelope posted to your endpoint.
The envelope every event is delivered in.
Responses
2XXAny success status
Your endpoint acknowledged the delivery. Any 2xx status within 30 seconds marks it delivered; the response body is ignored.
defaultAny other status
Any other status, a connection failure, or no answer within 30 seconds counts as a failed attempt. The delivery is retried 8 times, after 10 seconds, 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours, 1 day, 3 days; the last failure dead-letters it, and it can be retried from the dashboard or POST /v1/webhook-deliveries/{delivery}/retry. After 20 consecutive failures the endpoint is paused until it is resumed.
connector.disconnected
WEBHOOKAn installation was disconnected: the connector withdrew it, the credentials were wiped, the row stays.
When this fires
A creator disconnects an installation, from the Connectors tab, through the disconnect endpoint or the disconnect_connector tool. The connector withdraws the installation on its platform, the credentials are wiped and the installation turns disconnected; grants, resources, plans and identities are untouched and members keep the access they hold. Disconnecting an installation already disconnected fires nothing.
Caveats
- Disconnecting is not uninstalling: nothing is revoked and no plan is touched. Uninstalling, with its impact preview, is a separate act and fires
connector.uninstalled.
Related events
connector.connected: the reverse.connector.status_changed: a platform-side revocation, as opposed to the creator's own disconnect.
Ability to subscribe
A token needs this to subscribe an endpoint to the event.
Header Parameters
t=<unix seconds>,v1=<hex>: the HMAC-SHA256 of "<t>.<raw body>" under the endpoint's secret. Verify it before acting, and refuse a t more than 300 seconds from now. During a secret rotation a v0= signature under the previous secret may precede v1=.
The event's ULID, bare. The envelope's id is the same ULID prefixed evt_, so strip the prefix before comparing. Deduplicate on it: a retry carries the same id.
The event name, the same as the envelope's type.
Always application/json.
Always Subscriby-Webhooks/1.0.
Payload
JSONWhat Subscriby posts to your endpointapplication/json
The signed JSON envelope posted to your endpoint.
The envelope every event is delivered in.
Responses
2XXAny success status
Your endpoint acknowledged the delivery. Any 2xx status within 30 seconds marks it delivered; the response body is ignored.
defaultAny other status
Any other status, a connection failure, or no answer within 30 seconds counts as a failed attempt. The delivery is retried 8 times, after 10 seconds, 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours, 1 day, 3 days; the last failure dead-letters it, and it can be retried from the dashboard or POST /v1/webhook-deliveries/{delivery}/retry. After 20 consecutive failures the endpoint is paused until it is resumed.
connector.status_changed
WEBHOOKA probe or a verify moved an installation's state: connected, degraded or revoked.
When this fires
The hourly health probe, or a Verify run by the creator (the verify endpoint, verify_connector_installation), recorded a state other than the one the installation had. A probe that finds nothing changed fires nothing.
Caveats
reasonis a stable code in the connector's vocabulary; the sentence for it isstate_detailon the installation, read from the API.- A Disaster Recovery incident opens beside a
degradedstate that warrants a replacement; seerecovery.incident_opened.
Related events
connector.connected: a fresh connection that clears a degraded state.connector.disconnected: the creator withdrew it on purpose.
Ability to subscribe
A token needs this to subscribe an endpoint to the event.
Header Parameters
t=<unix seconds>,v1=<hex>: the HMAC-SHA256 of "<t>.<raw body>" under the endpoint's secret. Verify it before acting, and refuse a t more than 300 seconds from now. During a secret rotation a v0= signature under the previous secret may precede v1=.
The event's ULID, bare. The envelope's id is the same ULID prefixed evt_, so strip the prefix before comparing. Deduplicate on it: a retry carries the same id.
The event name, the same as the envelope's type.
Always application/json.
Always Subscriby-Webhooks/1.0.
Payload
JSONWhat Subscriby posts to your endpointapplication/json
The signed JSON envelope posted to your endpoint.
The envelope every event is delivered in.
Responses
2XXAny success status
Your endpoint acknowledged the delivery. Any 2xx status within 30 seconds marks it delivered; the response body is ignored.
defaultAny other status
Any other status, a connection failure, or no answer within 30 seconds counts as a failed attempt. The delivery is retried 8 times, after 10 seconds, 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours, 1 day, 3 days; the last failure dead-letters it, and it can be retried from the dashboard or POST /v1/webhook-deliveries/{delivery}/retry. After 20 consecutive failures the endpoint is paused until it is resumed.
connector.settings_updated
WEBHOOKA declared setting of an installation changed: which fields, never their values.
When this fires
A creator changes an installation's settings, on the dashboard, through the settings endpoint or the update_connector_installation_settings tool, and at least one declared field took a new value. A write that changes nothing fires nothing.
Caveats
- Values are never in the payload, and the installation endpoints never serialise settings either, because a settings field may be a secret. A consumer that needs the value asks the creator.
Related events
connector.connected: the installation the settings belong to.
Ability to subscribe
A token needs this to subscribe an endpoint to the event.
Header Parameters
t=<unix seconds>,v1=<hex>: the HMAC-SHA256 of "<t>.<raw body>" under the endpoint's secret. Verify it before acting, and refuse a t more than 300 seconds from now. During a secret rotation a v0= signature under the previous secret may precede v1=.
The event's ULID, bare. The envelope's id is the same ULID prefixed evt_, so strip the prefix before comparing. Deduplicate on it: a retry carries the same id.
The event name, the same as the envelope's type.
Always application/json.
Always Subscriby-Webhooks/1.0.
Payload
JSONWhat Subscriby posts to your endpointapplication/json
The signed JSON envelope posted to your endpoint.
The envelope every event is delivered in.
Responses
2XXAny success status
Your endpoint acknowledged the delivery. Any 2xx status within 30 seconds marks it delivered; the response body is ignored.
defaultAny other status
Any other status, a connection failure, or no answer within 30 seconds counts as a failed attempt. The delivery is retried 8 times, after 10 seconds, 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours, 1 day, 3 days; the last failure dead-letters it, and it can be retried from the dashboard or POST /v1/webhook-deliveries/{delivery}/retry. After 20 consecutive failures the endpoint is paused until it is resumed.
connector.uninstalled
WEBHOOKA connector was uninstalled from a project: its grants revoked, its resources detached, the installation row kept, with the counts of what that touched.
When this fires
A creator uninstalls a connector from a project, from the Connectors tab, through the uninstall endpoint or the uninstall_connector tool, after the impact preview. Uninstalling is distinct from disconnecting and never a deletion: every live grant on the connector's resources is revoked (member.resource_removed fires per grant), the resources are deactivated as detached with their external ids kept, the installation row stays with uninstalled_at, identities are never removed and no money moves by itself. The two opt-ins act on the plans left with nothing to grant: taking them off sale fires plan.deactivated per plan, cancelling their recurring subscriptions at period end fires subscription.cancelled per subscription.
Caveats
- Members are told by email that their recurring subscription will not renew; nothing is taken from them before the end of the paid period.
- Installing the connector again brings the same installation back as pending with its settings kept; the detached resources stay inactive until the creator relinks them.
Related events
connector.disconnected: the reversible act this is not.connector.installed: the reinstall.
Ability to subscribe
A token needs this to subscribe an endpoint to the event.
Header Parameters
t=<unix seconds>,v1=<hex>: the HMAC-SHA256 of "<t>.<raw body>" under the endpoint's secret. Verify it before acting, and refuse a t more than 300 seconds from now. During a secret rotation a v0= signature under the previous secret may precede v1=.
The event's ULID, bare. The envelope's id is the same ULID prefixed evt_, so strip the prefix before comparing. Deduplicate on it: a retry carries the same id.
The event name, the same as the envelope's type.
Always application/json.
Always Subscriby-Webhooks/1.0.
Payload
JSONWhat Subscriby posts to your endpointapplication/json
The signed JSON envelope posted to your endpoint.
The envelope every event is delivered in.
Responses
2XXAny success status
Your endpoint acknowledged the delivery. Any 2xx status within 30 seconds marks it delivered; the response body is ignored.
defaultAny other status
Any other status, a connection failure, or no answer within 30 seconds counts as a failed attempt. The delivery is retried 8 times, after 10 seconds, 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours, 1 day, 3 days; the last failure dead-letters it, and it can be retried from the dashboard or POST /v1/webhook-deliveries/{delivery}/retry. After 20 consecutive failures the endpoint is paused until it is resumed.
connector.doctor_completed
WEBHOOKThe connector doctor ran on an installation and found something different from the previous run.
When this fires
The creator pressed Run Doctor on the Connectors tab or the connector's page, an integration called the doctor endpoint or run_connector_doctor, or the platform's scheduled sweep ran, and the report differs from the one kept on the installation: a finding appeared, disappeared or changed severity or state. A run that finds exactly what the last one found fires nothing, so a nightly sweep is quiet until something moves. The installation's own verification inside the run still fires connector.status_changed when the state moved.
Caveats
- The first run on an installation fires this event, because there is no earlier report to match; a repeat with the same findings does not.
- A resource the connector has no place it can ask about (no space row, no legacy chat) is a
warningfinding, never left out. - Sentences are rendered in the creator's language at the time of the run; the
statewords are stable.
Related events
connector.status_changed: the installation's own verdict, fired by the verification inside the run when the state moved.
Ability to subscribe
A token needs this to subscribe an endpoint to the event.
Header Parameters
t=<unix seconds>,v1=<hex>: the HMAC-SHA256 of "<t>.<raw body>" under the endpoint's secret. Verify it before acting, and refuse a t more than 300 seconds from now. During a secret rotation a v0= signature under the previous secret may precede v1=.
The event's ULID, bare. The envelope's id is the same ULID prefixed evt_, so strip the prefix before comparing. Deduplicate on it: a retry carries the same id.
The event name, the same as the envelope's type.
Always application/json.
Always Subscriby-Webhooks/1.0.
Payload
JSONWhat Subscriby posts to your endpointapplication/json
The signed JSON envelope posted to your endpoint.
The envelope every event is delivered in.
Responses
2XXAny success status
Your endpoint acknowledged the delivery. Any 2xx status within 30 seconds marks it delivered; the response body is ignored.
defaultAny other status
Any other status, a connection failure, or no answer within 30 seconds counts as a failed attempt. The delivery is retried 8 times, after 10 seconds, 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours, 1 day, 3 days; the last failure dead-letters it, and it can be retried from the dashboard or POST /v1/webhook-deliveries/{delivery}/retry. After 20 consecutive failures the endpoint is paused until it is resumed.
connector.outage_opened
WEBHOOKA platform refused a project's live installation (token revoked or regenerated, bot deleted) and the connector entered an outage.
When this fires
The hourly health probe recorded a platform-caused refusal of a project's live installation: the platform says the credentials are revoked or regenerated, or that the bot or app no longer exists. Rate limits, unclassified errors, standby installations and a creator's own Disconnect never open an outage. A probe that repeats the same verdict does not fire this again; one outage stays open until connector.outage_closed.
While the outage is open, every plan that unlocks a place on that connector is off sale on the portal, in the bot, through access codes and trials and through the REST checkout, and the installation object reads sales_paused: true with an outage block. See Connector outages for what members and creators see.
Caveats
connector.status_changedfires beside this event withstate: degraded; this event is the narrower signal that sales froze.- A Disaster Recovery incident opens too when the refusal warrants a replacement; see
recovery.incident_opened.
Related events
connector.outage_closed: the outage ended.connector.status_changed: the state transition behind it.
Ability to subscribe
A token needs this to subscribe an endpoint to the event.
Header Parameters
t=<unix seconds>,v1=<hex>: the HMAC-SHA256 of "<t>.<raw body>" under the endpoint's secret. Verify it before acting, and refuse a t more than 300 seconds from now. During a secret rotation a v0= signature under the previous secret may precede v1=.
The event's ULID, bare. The envelope's id is the same ULID prefixed evt_, so strip the prefix before comparing. Deduplicate on it: a retry carries the same id.
The event name, the same as the envelope's type.
Always application/json.
Always Subscriby-Webhooks/1.0.
Payload
JSONWhat Subscriby posts to your endpointapplication/json
The signed JSON envelope posted to your endpoint.
The envelope every event is delivered in.
Responses
2XXAny success status
Your endpoint acknowledged the delivery. Any 2xx status within 30 seconds marks it delivered; the response body is ignored.
defaultAny other status
Any other status, a connection failure, or no answer within 30 seconds counts as a failed attempt. The delivery is retried 8 times, after 10 seconds, 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours, 1 day, 3 days; the last failure dead-letters it, and it can be retried from the dashboard or POST /v1/webhook-deliveries/{delivery}/retry. After 20 consecutive failures the endpoint is paused until it is resumed.
connector.outage_closed
WEBHOOKA connector outage ended: the installation answered again, another one took its place, or the creator uninstalled the connector.
When this fires
An open outage on a project's installation ended. ended_by says how: recovered when the probe found the installation healthy again or the creator reconnected it, replaced when another installation took over (a standby bot failed over, or the creator relinked a new bot), uninstalled when the creator removed the connector while the outage ran. Plans that were off sale return to sale at once.
The settlement follows from the queue and announces itself as connector.outage_compensated: invites that never reached a member during the outage are re-sent, and, when the outage lasted an hour or more, ended as recovered or replaced, and the project's Outage Compensation setting is on, every member whose paid access overlapped it has the outage's length banked on their purchase, one member.access_extended each. How the banked time reaches a member is described in Connector outages.
Caveats
- An
uninstalledend compensates nobody: the uninstall's own preview and opt-ins settle what members get. - Outages shorter than an hour end with this event too, but earn no compensation.
Related events
connector.outage_opened: the outage began.connector.outage_compensated: the settlement that follows this event.connector.connected: a fresh connection that ends arecoveredoutage.connector.uninstalled: the uninstall behind anuninstalledend.
Ability to subscribe
A token needs this to subscribe an endpoint to the event.
Header Parameters
t=<unix seconds>,v1=<hex>: the HMAC-SHA256 of "<t>.<raw body>" under the endpoint's secret. Verify it before acting, and refuse a t more than 300 seconds from now. During a secret rotation a v0= signature under the previous secret may precede v1=.
The event's ULID, bare. The envelope's id is the same ULID prefixed evt_, so strip the prefix before comparing. Deduplicate on it: a retry carries the same id.
The event name, the same as the envelope's type.
Always application/json.
Always Subscriby-Webhooks/1.0.
Payload
JSONWhat Subscriby posts to your endpointapplication/json
The signed JSON envelope posted to your endpoint.
The envelope every event is delivered in.
Responses
2XXAny success status
Your endpoint acknowledged the delivery. Any 2xx status within 30 seconds marks it delivered; the response body is ignored.
defaultAny other status
Any other status, a connection failure, or no answer within 30 seconds counts as a failed attempt. The delivery is retried 8 times, after 10 seconds, 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours, 1 day, 3 days; the last failure dead-letters it, and it can be retried from the dashboard or POST /v1/webhook-deliveries/{delivery}/retry. After 20 consecutive failures the endpoint is paused until it is resumed.
connector.outage_compensated
WEBHOOKA closed connector outage settled: how many members had time banked, how much each received, and how many invites lost during the outage were re-sent.
When this fires
Once per outage, shortly after connector.outage_closed. The settlement runs from the queue: it first re-sends any invite that never reached a member while the connector was refusing the installation (grants_replayed), then, when the outage lasted an hour or more, ended as recovered or replaced, and the project's Outage Compensation setting is on, banks the outage's length on every live purchase that unlocks a place on that connector (members_extended, one member.access_extended each). The creator receives the same summary by email, on their connected account and in the notification centre; it is also the Compensation column of the Recovery History page.
Caveats
- Fires with
members_extended: 0when the outage was shorter than an hour, ended with an uninstall, or the project switched Outage Compensation off; the creator is not emailed in that case. - Money never moves: no charge, refund or renewal date changes. Recurring members receive the time at the end of their membership.
Related events
member.access_extended: one per compensated member.connector.outage_closed: the outage this settles.
Ability to subscribe
A token needs this to subscribe an endpoint to the event.
Header Parameters
t=<unix seconds>,v1=<hex>: the HMAC-SHA256 of "<t>.<raw body>" under the endpoint's secret. Verify it before acting, and refuse a t more than 300 seconds from now. During a secret rotation a v0= signature under the previous secret may precede v1=.
The event's ULID, bare. The envelope's id is the same ULID prefixed evt_, so strip the prefix before comparing. Deduplicate on it: a retry carries the same id.
The event name, the same as the envelope's type.
Always application/json.
Always Subscriby-Webhooks/1.0.
Payload
JSONWhat Subscriby posts to your endpointapplication/json
The signed JSON envelope posted to your endpoint.
The envelope every event is delivered in.
Responses
2XXAny success status
Your endpoint acknowledged the delivery. Any 2xx status within 30 seconds marks it delivered; the response body is ignored.
defaultAny other status
Any other status, a connection failure, or no answer within 30 seconds counts as a failed attempt. The delivery is retried 8 times, after 10 seconds, 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours, 1 day, 3 days; the last failure dead-letters it, and it can be retried from the dashboard or POST /v1/webhook-deliveries/{delivery}/retry. After 20 consecutive failures the endpoint is paused until it is resumed.
How is this guide?