API reference for registering webhook endpoints to receive real-time notifications about transaction events and status updates.

Register Webhooks

Endpoint

POST /api/user/register-webhooks

Quick Start

curl -X POST https://api.tachyon.xyz/api/user/register-webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '[
    {
      "url": "https://myapp.com/webhook",
      "authType": "bearer",
      "secret": "my-bearer-token"
    },
    {
      "url": "https://api.example.com/tachyon-events",
      "authType": "api-key",
      "apiKeyPlacement": "header",
      "apiKeyVar": "X-API-Key",
      "secret": "my-api-key-value"
    },
    {
      "url": "https://myapp.com/public-webhook",
      "authType": "none"
    }
  ]'

Request

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`Authorization`	Yes	Bearer token with your Tachyon API key: `Bearer YOUR_API_KEY`

Body

The request body must be a JSON array of webhook registration objects. Each object must conform to the following schema:

Name	Type	Required	Description
`url`	`string`	Yes	Webhook endpoint URL. Must be a valid URL starting with `http://` or `https://`.
`authType`	`"none"` \| `"bearer"` \| `"basic"` \| `"api-key"`	Yes	Authentication method for securing webhook requests.
`secret`	`string`	Conditional	Secret/token value used for authentication. Required for `bearer` and `basic` auth types. For `api-key`, this is the API key value.
`apiKeyVar`	`string`	No	The header name or query parameter name where the API key should be sent. Used with `api-key` auth type.
`apiKeyPlacement`	`"header"` \| `"query"`	Conditional	Where to place the API key in the request. Required when `authType` is `"api-key"`.

Authentication Types

Auth Type	Description	Required Fields
`none`	No authentication. Webhook endpoint is publicly accessible.	None
`bearer`	Bearer token authentication. Token sent in `Authorization: Bearer {token}` header.	`secret`
`basic`	HTTP Basic authentication. Credentials sent in `Authorization: Basic {credentials}` header.	`secret`
`api-key`	API key authentication. Key can be sent in header or query parameter.	`secret`, `apiKeyPlacement`

Important Constraints

URL Validation: Webhook URL must start with http:// or https:// and be a valid URL format
API Key Placement: When using authType: "api-key", the apiKeyPlacement field is required
Secret Requirement: secret field is required for bearer, basic, and api-key authentication types

Response

Status Code: 200 OK

Response Body

Property	Type	Description
`userId`	`string`	The unique identifier of the user who registered the webhooks.
`address`	`string`	The wallet address associated with the user account.
`webhooks`	`WebhookConfig[]`	Array of registered webhook configurations.

WebhookConfig Object

Each webhook in the webhooks array contains:

Property	Type	Description
`url`	`string`	The registered webhook endpoint URL.
`authType`	`"none"` \| `"bearer"` \| `"basic"` \| `"api-key"`	The authentication method configured for this webhook.
`secret`	`string` (optional)	The secret/token value (may be masked or omitted for security).
`apiKeyVar`	`string` (optional)	The header or query parameter name for API key authentication.
`apiKeyPlacement`	`"header"` \| `"query"` (optional)	Where the API key is placed in requests.

Example Response

{
  "userId": "68c275846a6ba1c9a2198a8c",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "webhooks": [
    {
      "url": "https://myapp.com/webhook",
      "authType": "bearer"
    },
    {
      "url": "https://api.example.com/tachyon-events",
      "authType": "api-key",
      "apiKeyPlacement": "header",
      "apiKeyVar": "X-API-Key"
    },
    {
      "url": "https://myapp.com/public-webhook",
      "authType": "none"
    }
  ]
}

Examples

Bearer Token Authentication

curl -X POST https://api.tachyon.xyz/api/api/user/register-webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '[
    {
      "url": "https://myapp.com/webhook",
      "authType": "bearer",
      "secret": "my-secure-bearer-token"
    }
  ]'

Your webhook will receive requests with header:

Authorization: Bearer my-secure-bearer-token

API Key in Header

curl -X POST https://api.tachyon.xyz/api/user/register-webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '[
    {
      "url": "https://api.example.com/webhooks",
      "authType": "api-key",
      "apiKeyPlacement": "header",
      "apiKeyVar": "X-API-Key",
      "secret": "my-api-key-12345"
    }
  ]'

Your webhook will receive requests with header:

X-API-Key: my-api-key-12345

API Key in Query Parameter

curl -X POST https://api.tachyon.xyz/api/user/register-webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '[
    {
      "url": "https://api.example.com/webhooks",
      "authType": "api-key",
      "apiKeyPlacement": "query",
      "apiKeyVar": "apiKey",
      "secret": "my-api-key-12345"
    }
  ]'

Your webhook will receive requests at:

https://api.example.com/webhooks?apiKey=my-api-key-12345

Basic Authentication

curl -X POST https://api.tachyon.xyz/api/user/register-webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '[
    {
      "url": "https://myapp.com/webhook",
      "authType": "basic",
      "secret": "username:password"
    }
  ]'

Your webhook will receive requests with header:

Authorization: Basic base64(username:password)

No Authentication (Public Endpoint)

curl -X POST https://api.tachyon.xyz/user/register-webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '[
    {
      "url": "https://myapp.com/public-webhook",
      "authType": "none"
    }
  ]'

Your webhook receives requests without authentication headers.

Multiple Webhooks

curl -X POST https://api.tachyon.xyz/api/user/register-webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '[
    {
      "url": "https://myapp.com/webhook-1",
      "authType": "bearer",
      "secret": "token-1"
    },
    {
      "url": "https://myapp.com/webhook-2",
      "authType": "api-key",
      "apiKeyPlacement": "header",
      "apiKeyVar": "X-API-Key",
      "secret": "key-2"
    },
    {
      "url": "https://myapp.com/webhook-3",
      "authType": "none"
    }
  ]'

Use Cases

Transaction Monitoring: Receive real-time notifications when transactions are submitted, executed, or fail
Status Updates: Get notified about changes in transaction status across multiple chains
Event Tracking: Track specific events related to your relay transactions
Multi-Environment Setup: Register different webhooks for development, staging, and production environments
Microservices Architecture: Route transaction events to different services based on their purpose

Register Webhooks

On this page