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

# What are connection webhooks?

> An overview of connection webhooks: how they work, when to use them, and how they compare to polling.

# 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](https://www.standardwebhooks.com) specification, so you can verify authenticity.

## Core concepts

| Concept        | What it is                                                                                                                                   |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Webhook        | A registered HTTPS endpoint that receives signed event deliveries. Each webhook subscribes to one event type and has its own signing secret. |
| Event type     | The kind of event a webhook subscribes to. The only event type today is `connection.expiry_scheduled`.                                       |
| Signing secret | A `whsec_…` secret returned once, at webhook creation. Use it to verify the signature on each delivery. Store it securely.                   |
| Delivery       | A single HTTPS POST from Zapier to your `callback_url`, carrying a signed event payload.                                                     |

## 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](/white-label/connection-webhooks/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](/white-label/implementation/connection-flow#reconnecting).

First, you register your endpoint once:

```mermaid theme={null}
sequenceDiagram
    participant YourApp as Your backend
    participant Zapier
    YourApp->>Zapier: POST /connections/v1/webhooks (register endpoint)
    Zapier-->>YourApp: 201 Created + signing secret (once)
```

Later, each time a subscribed event occurs, Zapier delivers it:

```mermaid theme={null}
sequenceDiagram
    participant Zapier
    participant YourApp as Your backend
    participant User
    Zapier->>Zapier: Connection expiry scheduled
    Zapier->>YourApp: POST callback_url (signed event)
    YourApp->>YourApp: Verify signature
    YourApp->>User: Tell the user to reconnect
    User->>Zapier: Reconnect via Connect UI
```

## Supported events

| Event type                    | Fires when                                                                                                                                                                                          |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connection.expiry_scheduled` | A connection you manage is scheduled to expire and needs to be reconnected. The payload carries the scheduled `expires_at` time, ahead of the actual expiry, so you can prompt the user in advance. |

`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](/white-label/connection-webhooks/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](/white-label/trigger-inbox/what-is-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](/white-label/implementation/token-exchange#c-connection-webhooks-api-embedded).

<Note>
  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](mailto: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.
</Note>

Two scopes control access:

| Scope                      | Grants                                     |
| -------------------------- | ------------------------------------------ |
| `connection:webhook:read`  | List and retrieve webhooks.                |
| `connection:webhook:write` | Create, update, delete, and test webhooks. |

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](/white-label/connection-webhooks/verify-signatures).

## Next steps

1. [Connection webhooks quickstart](/white-label/connection-webhooks/connection-webhooks-quickstart): register a webhook and receive your first event.
2. [Verify signatures](/white-label/connection-webhooks/verify-signatures): confirm each delivery is authentic.
3. [Event payload reference](/white-label/connection-webhooks/payload-reference): the fields in a delivered event.
4. [Connections API reference](/api-reference/connections/connection-webhooks/create-a-connection-webhook): the CRUD endpoints.