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

Assuming you already have an endpoint URL, you can add a webhook integration in the platform.
1

Create Webhook Integration in Platform

In the platform, go to Integrations → Add Integration → select Webhook, then supply the webhook details:
  • URL: The endpoint that will receive events
  • Headers: Any custom headers required by your endpoint (e.g., authentication)
  • Body: The JSON payload template your endpoint expects
2

Attach Webhook to Agents

After creating the integration, attach the webhook to individual agents. When those agents run and emit events, your webhook will be invoked with the configured details.
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 occurredExample: 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": "[email protected]",
    "name": "John Doe",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

​
Troubleshooting