Overview

Vortex API webhooks allow you to receive real-time notifications when transaction events occur, eliminating the need to continuously poll the API for status updates.

This guide provides everything you need to integrate webhooks into your application.

Vortex webhooks allow you to monitor transaction lifecycle events in real-time. You can register webhooks to receive notifications for:

Transaction creation - When a new ramp transaction is registered

Status changes - When a transaction's status changes (pending → complete/failed)

Security Model

All webhook requests include security headers for verification:

X-Vortex-Signature: RSA-PSS signature of the request body

X-Vortex-Timestamp: Unix timestamp of the request

HTTPS Required: All webhook URLs must use HTTPS

Event Types

TRANSACTION_CREATED

Triggered when a new ramp transaction is registered through the POST /v1/ramp endpoint.

Timing: Immediately after the ramp state is created in the database.

Payload Structure:

{
  "eventType": "TRANSACTION_CREATED",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "payload": {
    "quoteId": "quote-123",
    "transactionId": "tx-123",
    "sessionId": "session-456",
    "transactionStatus": "PENDING",
    "transactionType": "BUY"
  }
}

Fields:

quoteId: Unique identifier for the quote

transactionId: Unique indentifier for the transaction

sessionId: Session identifier (if provided during registration)

transactionStatus: Always "PENDING" for new transactions

transactionType: "BUY" (onramp) or "SELL" (offramp)

STATUS_CHANGE

Triggered when a transaction's phase changes during processing.

Timing: Whenever the transaction phase is updated (PENDING → COMPLETE/FAILED).

Payload Structure:

{
  "eventType": "STATUS_CHANGE",
  "timestamp": "2025-01-15T10:35:00.000Z",
  "payload": {
    "quoteId": "quote-123",
    "transactionId": "tx-123",
    "sessionId": "session-456",
    "transactionStatus": "COMPLETE",
    "transactionType": "BUY"
  }
}

Status Mapping:

"PENDING": Transaction is in progress

"COMPLETE": Transaction completed successfully

"FAILED": Transaction failed or timed out

Example Webhook Listener Service

Here's a complete example of a webhook listener service built with Bun:

Retry Mechanism

Vortex implements automatic retries for failed webhook deliveries:

Retry Attempts: Up to 5 attempts

Backoff Strategy: Exponential (1s, 2s, 4s, 8s, 16s)

Timeout: 30 seconds per request

Deactivation: Webhooks are automatically deactivated after 5 consecutive failures

Security Best Practices

1. Validate Signature

Always verify the X-Vortex-Signature header using RSA-PSS to ensure the request is from Vortex. Use the public key from /v1/public-key:

2. Validate Timestamps

Check the X-Vortex-Timestamp header to prevent replay attacks:

Security Model#

Event Types#

TRANSACTION_CREATED#

STATUS_CHANGE#

Example Webhook Listener Service#

Retry Mechanism#

Security Best Practices#

1. Validate Signature#

2. Validate Timestamps#