Skip to main content

​
What are connection webhooks?

Connection webhooks let your White Label (partner) account subscribe to events about the app connections you manage. An app connection is an end user’s authenticated link to a third-party app, for example their Slack or Google account. You register an HTTPS endpoint once, and Zapier POSTs a signed event to it when something happens to one of those app connections. For brevity, the rest of this guide calls an app connection a connection. Today there is one event type: a connection is scheduled to expire and needs to be reconnected. More event types may be added over time, and the API is designed so you subscribe to the specific event types you care about. Use these events to react to connection changes programmatically instead of polling connection status on a schedule. For the expiry event, that means telling your end users to reconnect an app before their automations stop working.

​
Key benefits

  • No polling: Zapier pushes events to your endpoint, so you do not have to poll each connection for its status.
  • Signed deliveries: Every event is signed with a per-webhook secret following the Standard Webhooks specification, so you can verify authenticity.

​
Core concepts

​
How it works

  1. Register a webhook. Create a webhook with your HTTPS callback_url and the event type you want. Store the signing secret from the response.
  2. An event occurs. For example, Zapier determines that a connection you manage is scheduled to expire.
  3. Zapier POSTs an event. Zapier sends a signed event to your callback_url.
  4. Verify the signature. Your endpoint verifies the signature with your signing secret. For the steps, go to Verify signatures.
  5. React to the event. For the expiry event, use the connection_id from the payload to tell the user to start a reconnection flow.
First, you register your endpoint once: Later, each time a subscribed event occurs, Zapier delivers it:

​
Supported events

connection.expiry_scheduled is the only event type today. New event types may be added later, so treat an unknown type as one to ignore rather than an error. For the full payload shape, go to Event payload reference.

​
When to use connection webhooks

Connection webhooks are a good fit when you manage connections on behalf of your end users and want to react to connection changes without polling. Use them if you are:
  • Managing app connections for your end users through a White Label account
  • Reacting to connection lifecycle changes (today, expiry) programmatically
  • Building reconnection flows that need to run before a connection expires
Connection webhooks report events about connections. To receive events from connected apps (for example, a new Slack message), use the Trigger Inbox API instead.

​
Security and authentication

The Connections API uses OAuth 2.0 bearer tokens. All API requests must include an Authorization: Bearer YOUR_ACCESS_TOKEN header. To obtain a token, go to Token exchange: Connection Webhooks API.
While this API is in early access, partners need a separate, dedicated client ID and secret to exchange for an access token that works with the connection webhooks endpoints. Reach out to whitelabel@zapier.com and we will help you set it up. This is temporary: we are working so you can use your original client ID and secret to obtain a token that works across all White Label APIs, including connection webhooks.
Two scopes control access: Each event delivery is signed with the webhook’s signing secret. Always verify the signature before you trust a payload. For the steps, go to Verify signatures.

​
Next steps

  1. Connection webhooks quickstart: register a webhook and receive your first event.
  2. Verify signatures: confirm each delivery is authentic.
  3. Event payload reference: the fields in a delivered event.
  4. Connections API reference: the CRUD endpoints.