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

# Webhooks

> Create and manage webhooks to receive real-time event notifications from the Paxos platform.

Use [Webhooks](https://dashboard.paxos.com/dashboard/webhooks) in Dashboard to create and manage webhook integrations that receive asynchronous event notifications when events occur on the Paxos platform.

<Note>
  * Each entity can have a maximum of **10 active webhooks**
  * Webhook names must be **unique** within your account
</Note>

For a complete guide on setting up webhook consumers and integrating with the Paxos platform, see the [Webhooks Developer Guide](/guides/webhooks).

## View Webhooks

Navigate to the [Webhooks](https://dashboard.paxos.com/dashboard/developer/webhooks) section under the Developer tab to view all configured webhooks for your account.

Each webhook displays:

* **Name**: The unique identifier for your webhook
* **URL**: The endpoint URL where events are delivered
* **Auth Type**: The authentication method (API Key or OAuth)
* **Created At**: When the webhook was created
* **Updated At**: When the webhook was last updated
* **Status**: Current status (Active, Pending, etc.)
* **Actions**: Available actions (View, Test, Delete)

Click **View** to display more details about your webhook, including event types, rate limit (requests per second), and approval history.

## Create a Webhook

Before creating a webhook in Dashboard, ensure you have a webhook consumer endpoint ready to receive events. See [Create a Webhook Consumer](/guides/webhooks/quickstart#create-a-webhook-consumer) for implementation examples.

To create a new webhook:

1. Navigate to [Webhooks](https://dashboard.paxos.com/dashboard/webhooks)
2. Click **Create Webhook**
3. Configure the webhook settings:
   * **Name**: Enter a unique name for your webhook
   * **URL**: Enter your webhook consumer endpoint URL (must be HTTPS)
   * **Auth Type**: Select your authentication method (API Key or OAuth)
   * **Authentication**: Configure your selected authentication method:
     * **API Key**: Provide the header name and API key value that Paxos will include in webhook requests
     * **OAuth**: Provide the OAuth endpoint URL, Client ID, and Client Secret
   * **Event Types**: Select which events you want to receive (Identity, Transfer, Orchestration, etc.)
   * **Rate Limit**: Set the delivery rate limit (1-100 requests per second, default is 10)
4. Click **Create** to save the webhook

Once created, the webhook will show an **Active** status and begin receiving events based on your selected event types.

### OAuth2 client authentication

When using OAuth2 authentication, Paxos obtains access tokens by sending a POST request to the configured `client_url` using the [OAuth2 client credentials grant](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1).

Paxos supports both standard client authentication methods and sends them simultaneously in token requests to maximize compatibility with OAuth2 providers:

| Method                              | Description                                                       | Format                                                                         |
| ----------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `client_secret_basic` (recommended) | Client credentials sent in the Authorization header as Basic auth | `Authorization: Basic base64(url_encode(client_id):url_encode(client_secret))` |
| `client_secret_post`                | Client credentials sent in the request body as form parameters    | `client_id=xxx&client_secret=yyy`                                              |

The request body always includes `grant_type=client_credentials` using `application/x-www-form-urlencoded` format.

<Info>
  Paxos supports approvals for creating and deleting webhooks. You can enable approvals for webhooks via the Admin → [Approvals](/guides/dashboard/admin/approvals) tab to add an additional layer of security and control.
</Info>

## Test a Webhook

After creating a webhook, use the Test feature to verify your consumer endpoint is configured correctly:

1. Navigate to [Webhooks](https://dashboard.paxos.com/dashboard/webhooks)
2. Click **Actions** → **Test** for the webhook you want to test
3. Select an event type to send as a test event
4. Click **Send Test Event**

The test event will be sent to your endpoint with `is_test=true` in the payload. Verify that your consumer receives and processes the event correctly.

<Info>
  For information on handling test events in your consumer code, see the [webhook consumer examples](/guides/webhooks/quickstart#create-a-webhook-consumer).
</Info>

## Update a Webhook

To update an existing webhook:

1. Navigate to [Webhooks](https://dashboard.paxos.com/dashboard/webhooks)
2. Click **View** for the webhook you want to update
3. Click **Edit**
4. Modify any combination of the following settings:
   * **Name**: Update the webhook name
   * **URL**: Change the endpoint URL
   * **Event Types**: Add or remove event subscriptions
   * **Auth Type and Credentials**: Update authentication configuration
   * **Rate Limit**: Adjust the requests per second limit
5. Click **Update Webhook** to apply your changes, or **Submit for Approval** if approvals are required

<Info>
  If [approvals](/guides/dashboard/admin/approvals) are enabled for webhooks, updates will require approval before taking effect.
</Info>

## Delete a Webhook

To delete a webhook:

1. Navigate to [Webhooks](https://dashboard.paxos.com/dashboard/webhooks)
2. Click **Actions** → **Delete** for the webhook you want to remove
3. Confirm the deletion

Once deleted, the webhook will no longer receive events and will not count toward your 10 webhook limit.

### Errored webhooks

You should rarely see webhooks in an error state. Errors only occur when making modifications (Create, Update, or Delete) — there is no risk of webhooks randomly entering the error state once active. If this occurs, you can delete problematic webhooks and create new ones from the Dashboard.

## Webhook Delivery and Monitoring

To view and monitor webhook events, including filtering by date, event type, and delivery status, see [Events](/guides/dashboard/events).

For information about webhook delivery behavior, retry policies, and rate limits, see the [Retries and Limits](/guides/webhooks/retries-and-limits) guide.