Rath Docs – Universal Rails For DeFi Yield

`registerWebhooks()`

Register webhook endpoints to receive real-time notifications about transaction events and status updates for your Tachyon relay operations.

Quick Start


import { Tachyon } from '@rathfi/tachyon';
 
// Initialize the SDK
const tachyon = new Tachyon({
  apiKey: 'YOUR_API_KEY',
});
 
// Register webhooks
const webhooks = await tachyon.registerWebhooks([
  {
    url: 'https://your-app.com/webhooks/tachyon',
    authType: 'bearer',
    secret: 'your-webhook-secret',
    enabled: true,
  },
  {
    url: 'https://your-app.com/webhooks/backup',
    authType: 'api-key',
    secret: 'your-api-key',
    apiKeyVar: 'X-API-Key',
    apiKeyPlacement: 'header',
    enabled: true,
  }
]);
 
console.log('Registered webhooks for user:', webhooks.userId);
console.log('Associated address:', webhooks.address);
console.log('Active webhooks:', webhooks.webhooks);

Methods

`registerWebhooks(payload)`

Registers one or more webhook endpoints to receive notifications about transaction events. You can configure multiple webhooks with different authentication methods for redundancy and flexibility.

Parameters

The registerWebhooks() method accepts an array of WebhookRegistrationInput objects with the following properties:

Name	Type	Required	Description
`url`	`string`	Yes	The HTTPS endpoint URL where webhook notifications will be sent. Must be a valid, publicly accessible URL.
`authType`	`"none"` \| `"bearer"` \| `"basic"` \| `"api-key"`	Yes	Authentication method for securing webhook requests. Options: `"none"` (no authentication), `"bearer"` (Bearer token), `"basic"` (Basic auth), `"api-key"` (API key).
`secret`	`string`	No	Secret/token used for authentication. Required when `authType` is `"bearer"`, `"basic"`, or `"api-key"`.
`apiKeyVar`	`string`	No	The name of the API key variable (e.g., `"X-API-Key"`, `"api_key"`). Required when `authType` is `"api-key"`.
`apiKeyPlacement`	`"header"` \| `"query"`	No	Where to place the API key: in the request header or as a query parameter. Required when `authType` is `"api-key"`.
`enabled`	`boolean`	Yes	Whether this webhook is active. Set to `false` to temporarily disable without deleting the configuration.

Authentication Types

None ("none")

No authentication required
Use only for testing or internal endpoints

Bearer Token ("bearer")

Sends Authorization: Bearer {secret} header
Recommended for most use cases

Basic Auth ("basic")

Sends Authorization: Basic {base64(secret)} header
Compatible with basic HTTP authentication

API Key ("api-key")

Flexible API key placement
Can be sent in header or query parameter
Specify custom variable name

Response

Returns: Promise<WebhookRegistrationResponse>

The WebhookRegistrationResponse object contains:

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

WebhookConfig Object

Property	Type	Description
`url`	`string`	The registered webhook endpoint URL.
`authType`	`WebhookAuthType`	The authentication method configured.
`secret`	`string`	The authentication secret (may be masked for security).
`enabled`	`boolean`	Whether the webhook is currently active.

Example Output

webhook-config.json


{
  "userId": "usr_1234567890abcdef",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "webhooks": [
    {
      "url": "https://your-app.com/webhooks/tachyon",
      "authType": "bearer",
      "secret": "***************",
      "enabled": true
    },
    {
      "url": "https://your-app.com/webhooks/backup",
      "authType": "api-key",
      "secret": "***************",
      "enabled": true
    }
  ]
}

Authentication Examples

Bearer Token Authentication


const webhooks = await tachyon.registerWebhooks([
  {
    url: 'https://api.yourapp.com/webhooks',
    authType: 'bearer',
    secret: 'your-secret-bearer-token',
    enabled: true,
  }
]);

API Key in Header


const webhooks = await tachyon.registerWebhooks([
  {
    url: 'https://api.yourapp.com/webhooks',
    authType: 'api-key',
    secret: 'your-api-key-value',
    apiKeyVar: 'X-API-Key',
    apiKeyPlacement: 'header',
    enabled: true,
  }
]);

API Key in Query Parameter


const webhooks = await tachyon.registerWebhooks([
  {
    url: 'https://api.yourapp.com/webhooks',
    authType: 'api-key',
    secret: 'your-api-key-value',
    apiKeyVar: 'api_key',
    apiKeyPlacement: 'query',
    enabled: true,
  }
]);

Basic Authentication


const webhooks = await tachyon.registerWebhooks([
  {
    url: 'https://api.yourapp.com/webhooks',
    authType: 'basic',
    secret: 'username:password',
    enabled: true,
  }
]);

No Authentication (Testing Only)


const webhooks = await tachyon.registerWebhooks([
  {
    url: 'https://your-dev-server.com/test-webhooks',
    authType: 'none',
    enabled: true,
  }
]);

Use Cases

Real-time notifications: Receive instant updates when transactions are confirmed or fail.
Transaction monitoring: Track the status of relay operations across multiple chains.
Automated workflows: Trigger business logic in your application based on transaction events.
Redundancy: Configure multiple webhook endpoints for high-availability systems.
Audit logging: Maintain a record of all transaction events in your own database.

Best Practices

Use HTTPS: Always use secure HTTPS endpoints for webhook URLs.
Implement retry logic: Handle webhook delivery failures gracefully on your server.
Validate signatures: Verify the authenticity of incoming webhook requests.
Enable selectively: Set enabled: false for webhooks during maintenance without deleting them.
Monitor webhook health: Track delivery success rates and response times.
Use strong secrets: Generate cryptographically secure tokens for authentication.