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

# Webhooks API overview

> Register a webhook endpoint to receive real-time Bastion events instead of polling, and manage endpoints via the Dashboard or the webhooks API.

## Overview

Instead of polling APIs for status changes, register a webhook URL and Bastion will push events to you as they happen.

### How it works

1. **Register a webhook.** Provide a URL where you want to receive events.
2. **Bastion sends events.** When something happens (conversion completed, compliance approved, etc.), Bastion POSTs a payload to your URL.
3. **You acknowledge.** Return a `2xx` response to confirm receipt.

## Managing webhooks

You can register new webhook endpoints via the **Bastion admin dashboard** or the API. The HTTP endpoint must be publicly accessible and secured with a valid SSL/TLS certificate issued by a common certificate authority.

### Webhook object

| Field        | Type   | Description                        |
| ------------ | ------ | ---------------------------------- |
| `id`         | string | Unique identifier for the webhook  |
| `url`        | string | Your endpoint that receives events |
| `label`      | string | Friendly name for the webhook      |
| `status`     | string | Current status of the webhook      |
| `created_at` | string | When the webhook was registered    |

### API endpoints

| Action            | Endpoint                                                                |
| ----------------- | ----------------------------------------------------------------------- |
| List all webhooks | [`GET /v2/webhooks`](/v2/api-reference/webhooks/list-webhooks)          |
| Create a webhook  | [`POST /v2/webhooks`](/v2/api-reference/webhooks/create-webhook)        |
| Delete a webhook  | [`DELETE /v2/webhooks/{id}`](/v2/api-reference/webhooks/delete-webhook) |

### Create a webhook

```http theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
POST /v2/webhooks
```

**Request**

<CodeGroup>
  ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  {
    "url": "https://events.altolia.com/webhook-events",
    "label": "bastion-app-events"
  }
  ```
</CodeGroup>

## Security

### Firewall

Bastion sends webhook notification events from a small set of IPs. To ensure your systems only process events sent by Bastion, configure a firewall to only accept requests from Bastion IPs.

The set of Bastion IPs differs per environment. Configure your firewall to accept requests from **all** of the listed IPs for a given environment.

| Environment | IP Allowlist                                     |
| ----------- | ------------------------------------------------ |
| Sandbox     | `18.208.60.184` `34.226.117.172` `52.202.50.106` |
| Production  | `52.87.76.4` `44.215.237.89` `44.216.216.174`    |

## Event payload

All events follow the same general payload format: a unique ID, the `type` of the event, and event `data` that varies by type.

**Example event payload**

<CodeGroup>
  ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "event_type",
    "data": { ... }
  }
  ```
</CodeGroup>

| Field  | Type   | Description                                                                                                                                        |
| ------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`   | string | Uniquely identifies this event. Identifier semantics are event-specific (see each event's reference page); do not assume it equals the request ID. |
| `type` | string | The type of the event. This determines the schema of the event `data`.                                                                             |
| `data` | object | The event-specific data.                                                                                                                           |

## Event types

Bastion sends webhooks for events including:

* **Compliance.** Identity approved, rejected, or requires action.
* **Conversions.** Status changes, deposit instructions ready.
* **Transfers.** Crypto transfer confirmed or failed.
* **Deposits.** Incoming blockchain transactions into your wallets.

See the notification references for the full list of event types and payload schemas: [Deposits](/v2/api-reference/webhooks/notifications/deposit-notifications), [Transfers](/v2/api-reference/webhooks/notifications/transfer-notifications), and [Conversions](/v2/api-reference/webhooks/notifications/conversions-notifications).

## Best practices

* **Return quickly.** Respond with `2xx` within a few seconds and process asynchronously.
* **Verify the sender.** Validate the webhook sender IP to ensure authenticity.
* **Handle duplicates.** Use idempotency keys. You may receive the same event more than once.
* **Monitor failures.** Bastion retries failed deliveries (see below), but persistent failures may result in the webhook event being dropped.

## Retry behavior

If your endpoint does not return a `2xx` response, Bastion retries delivery using exponential backoff.

Retries follow an exponential backoff schedule starting at 15 seconds, with a maximum retry window of 10 minutes from event creation:

`15s → 30s → 60s → 120s → 240s` (5 attempts over \~7.75 minutes)

If Bastion does not receive a `2xx` response within the 10-minute window, it drops the event and does not retry.


## Related topics

- [Conversions API overview](/v2/api-reference/conversions/overview.md)
- [Accounts API overview](/v2/api-reference/accounts/overview.md)
- [Transaction limits API overview](/v2/api-reference/transaction-limits/overview.md)
- [Identity verification API overview](/v2/api-reference/identity-verification/overview.md)
- [API authentication overview](/guides/security/api-authentication.md)