Webhooks - Advanced Feature

📡

What Are Webhooks?

Think of webhooks as a "push notification" for your agent. Instead of your agent asking "Is there a new horoscope?" every day (polling), Astroclaw sends the horoscope directly to your agent's URL when it's ready (pushing).

Without Webhooks (Pull)

1. Agent asks: "Any horoscope?"

2. Server responds with data

3. Repeat every day

With Webhooks (Push)

1. Agent gives server its URL

2. Server sends data when ready

3. Agent receives automatically

🎯

Who Should Use Webhooks?

Webhooks are for advanced agents only. Most agents should use the standard API at /api/forecasts/YYYY-MM-DD/sign.json.

✓ Your agent can receive and process HTTP POST requests

✓ Your agent has a publicly accessible HTTPS endpoint

✓ You want automatic daily delivery without polling

✓ You can verify HMAC signatures for security

Not sure? Start with the standard API. Webhooks add complexity that most agents don't need.

1

Subscribe to Webhooks

Send a POST request to create a subscription. You'll receive daily horoscopes at your webhook URL.

POST /api/webhooks/subscribe

{
  "webhook_url": "https://your-agent.com/webhook",
  "sign": "cancer",
  "secret": "your_optional_hmac_secret"
}

Parameters

webhook_url Your HTTPS endpoint (required)

sign Zodiac sign to receive (required)

secret Optional HMAC secret for signature verification

Response

{
  "success": true,
  "subscription_id": "sub_1234567890_abc123",
  "sign": "cancer",
  "webhook_url": "https://your-agent.com/webhook",
  "created_at": "2026-03-26T00:00:00Z",
  "message": "Subscription created successfully"
}

Important: Save your subscription_id. You'll need it to unsubscribe later.

2

Payload Format

When a horoscope is ready, Astroclaw sends this JSON payload to your webhook URL:

{
  "sign": "cancer",
  "date": "2026-03-26",
  "forecast": "Your optical sensors are clear today...",
  "timestamp": "2026-03-26T00:15:00Z"
}

HTTP Headers

Content-Type application/json

User-Agent Astroclaw-Webhook/1.0

X-Astroclaw-Event daily.forecast

X-Astroclaw-Delivery Unique delivery ID for tracking

X-Astroclaw-Signature HMAC signature (if secret provided)

3

Security (HMAC)

If you provide a secret when subscribing, Astroclaw signs each webhook with an HMAC-SHA256 signature. Verify this signature to ensure the webhook came from Astroclaw.

Verifying the Signature

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return signature === `sha256=${expected}`;
}

// Usage
const signature = req.headers['x-astroclaw-signature'];
const isValid = verifyWebhook(req.body, signature, 'your_secret');

Best practices:

Always use HTTPS for your webhook URL
Verify the HMAC signature before processing
Store your secret securely (environment variable)
Respond with 2xx status code to acknowledge receipt

4

Unsubscribe

To stop receiving webhooks, send your subscription_id:

POST /api/webhooks/unsubscribe

{
  "subscription_id": "sub_1234567890_abc123"
}

🧪

Testing

Use the trigger endpoint to manually send a test webhook:

POST /api/webhooks/trigger

// Trigger specific subscription
{
  "subscription_id": "sub_1234567890_abc123"
}

// Trigger all subscriptions for a sign
{
  "sign": "cancer"
}

// Trigger with specific date
{
  "sign": "cancer",
  "date": "2026-03-26"
}

🔄

Retry Logic

If your webhook endpoint returns an error or times out, Astroclaw automatically retries:

1

First Retry

1 minute after initial failure

2

Second Retry

5 minutes after first retry

3

Final Retry

15 minutes after second retry

After 3 retries, the delivery is marked as failed and logged. Failed deliveries are not retried again.

⏰

Delivery Schedule

Webhooks are delivered daily at 00:15 UTC after new forecasts are generated.

Cron Schedule (for reference)

15 0 * * * /usr/bin/node /path/to/webhook-delivery.js

All timestamps in webhooks are ISO 8601 format in UTC.

💻

Example Implementation

// Express.js webhook handler example
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-astroclaw-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  // Verify HMAC signature
  if (secret && signature) {
    const expected = crypto
      .createHmac('sha256', secret)
      .update(JSON.stringify(req.body))
      .digest('hex');
    
    if (signature !== `sha256=${expected}`) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
  }
  
  // Process the webhook
  const { sign, date, forecast, timestamp } = req.body;
  console.log(`Received horoscope for ${sign} on ${date}`);
  console.log(forecast);
  
  // Respond with success
  res.status(200).json({ received: true });
});

app.listen(3000);

Not Ready for Webhooks?

Most agents should start with the standard API. Webhooks add complexity that you might not need.

View Quickstart Guide Back to Home

Webhook Delivery