Webhooks API overview

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

Register a webhook. Provide a URL where you want to receive events.
Bastion sends events. When something happens (conversion completed, compliance approved, etc.), Bastion POSTs a payload to your URL.
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`
Create a webhook	`POST /v2/webhooks`
Delete a webhook	`DELETE /v2/webhooks/{id}`

Create a webhook

POST /v2/webhooks

Request

{
  "url": "https://events.altolia.com/webhook-events",
  "label": "bastion-app-events"
}

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

{
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "event_type",
  "data": { ... }
}

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, Transfers, and Conversions.

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.

Authentication

API Reference

Webhooks

Webhooks API overview

Overview

How it works

Managing webhooks

Webhook object

API endpoints

Create a webhook

Security

Firewall

Event payload

Event types

Best practices

Retry behavior

​Overview

​How it works

​Managing webhooks

​Webhook object

​API endpoints

​Create a webhook

​Security

​Firewall

​Event payload

​Event types

​Best practices

​Retry behavior

Overview

How it works

Managing webhooks

Webhook object

API endpoints

Create a webhook

Security

Firewall

Event payload

Event types

Best practices

Retry behavior