Webhooks allow you to receive real-time notifications when events occur in your application. Set up HTTP endpoints to automatically receive event data as it happens.

​
Overview

Real-time Notifications

Get instant updates when events occur in your system

Secure Delivery

Webhooks are signed with cryptographic signatures for verification

Reliable Delivery

Automatic retries ensure your webhooks are delivered

Easy Integration

Simple HTTP POST requests to your specified endpoints

​
Configuration

​
Setting Up Your Webhook

1

Configure Endpoint URL

Provide the HTTP endpoint where you want to receive webhook notifications.

https://webhook.site/your-unique-url
2

Add Custom Headers

Configure any custom headers you need for authentication or routing.

HeaderValueDescription
AuthorizationBearer tokenAuthentication token
Content-Typeapplication/jsonAlways set to JSON
X-Custom-Headercustom-valueAny custom headers you need
3

Verify Webhook Signature

All webhooks include a cryptographic signature for security verification.

​
Webhook Payload

Every webhook request contains a standardized payload structure:

{
  "type": "<event_type>",
  "timestamp": "<timestamp>",
  "payload": "<event_payload>"
}

​
Payload Parameters

​
type
string
required

The type of event that triggered the webhook. Examples: user.created, payment.completed, order.updated

​
timestamp
string
required

ISO 8601 timestamp when the event occurred

Example: 2024-01-15T10:30:00Z

​
payload
object
required

The actual event data. Structure varies depending on the event type.

​
Security & Signature Verification

All webhooks are signed using SHA256 hashing with RSA-PKCS1v15 signing and Base64 encoding for maximum security.

​
Signature Header

The webhook signature is included in the X-Asteroid-Signature header:

X-Asteroid-Signature: <signature>

Always verify the webhook signature to ensure the request is authentic and hasn’t been tampered with.

​
Public Key for Verification

Use this Base64-encoded public key to verify webhook signatures:

LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUF0SkZ6aXdXUjROUVJzTnpqZw==

​
JavaScript Implementation

Here’s a complete example of verifying webhook signatures in JavaScript:

const crypto = require('crypto');

// Step 1: Create SHA256 verifier
const verifier = crypto.createVerify('SHA256');

// Step 2: Update verifier with the request body
verifier.update(body);

// Step 3: Convert Base64 public key to buffer
const publicKey = Buffer.from(publicKeyBase64, 'base64');

// Step 4: Verify the signature
const isValid = verifier.verify(publicKey, signature, 'base64');

console.log('Signature valid:', isValid);

​
Best Practices

​
Testing Your Webhooks

Use webhook.site to test your webhook integration during development. It provides a temporary URL that captures and displays all incoming webhook requests.

​
Test Payload Example

{
  "type": "user.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "payload": {
    "user_id": "usr_123456789",
    "email": "user@example.com",
    "name": "John Doe",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

​
Troubleshooting