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

# Webhook Subscriptions

## Webhook Subscriptions

Webhook subscriptions allow you to receive real-time notifications about events in your PassEntry account. When an event occurs (like a pass being installed or scanned), PassEntry will send an HTTP POST request to your specified endpoint with details about the event.

<Warning>
  This section covers webhook subscriptions and management. For webhook events and security best practices, see the [Webhooks](/api-reference/v1/webhooks/guide) section.
</Warning>

### Setting Up Webhooks

To start receiving webhooks, create a subscription either via API or [PassEntry Dashboard](https://app.passentry.com/developer-tools).

1. Create a webhook subscription by providing:
   * An HTTPS endpoint URL that will receive the webhook events
   * A list of events you want to subscribe to
   * Optional entity scope if you want to receive events only for a specific entity

2. Store the secret key returned in the response securely. This key is used to verify webhook signatures (see [Security Measures](/api-reference/v1/webhooks/guide#security-measures)).

3. Configure your endpoint to:
   * Accept POST requests
   * Verify webhook signatures
   * Return a 2xx status code to acknowledge receipt

### Webhook Management

#### Scoping

* Your entire organisation (default)
* A specific entity (if you have multiple entities)

**Important Limitations:**

* Cannot create multiple webhook subscriptions with the same target URL within the same scope
* Cannot change the scope after subscription creation (create a new one and delete the old one)
* Default limits: 10 organisation-level and 10 per entity subscriptions

#### Status

* **Enabled**: Actively receiving events
* **Disabled**: Temporarily paused

### Debugging and Security

* Use the "Test webhook" functionality via [API](/api-reference/v1/webhook-subscriptions/test-webhook-subscription) or [Dashboard](https://app.passentry.com/developer-tools) to debug your subscriptions
* If you believe your secret key was compromised, rotate it via [Dashboard](https://app.passentry.com/developer-tools) or [API](/api-reference/v1/webhook-subscriptions/rotate-secret-key)
* Maintain separate webhook subscriptions for each environment (development, staging, production) to isolate testing and ensure proper event handling across your deployment pipeline

For implementation details and best practices, see our [Webhooks Guide](/api-reference/v1/webhooks/guide).