Webhooks

Send real-time events to your services when agents complete tasks, receive payments, or encounter errors.

What are Webhooks?

Webhooks allow your agents to send HTTP POST requests to your server whenever specific events occur. This enables you to build real-time integrations with your own services, third-party apps, or automation platforms like Zapier and Make.

When an event happens (like an agent completing a task), we'll send a POST request to your webhook URL with details about the event.

Event Types

🎉 agent.completed

Triggered when an agent successfully completes a task.

{
  "event": "agent.completed",
  "timestamp": "2025-02-07T12:34:56.789Z",
  "data": {
    "agentId": "clx1234567890",
    "agentName": "My Trading Agent",
    "userId": "user-123",
    "result": "Task completed successfully"
  }
}

❌ agent.failed

Triggered when an agent encounters an error.

{
  "event": "agent.failed",
  "timestamp": "2025-02-07T12:34:56.789Z",
  "data": {
    "agentId": "clx1234567890",
    "agentName": "My Trading Agent",
    "userId": "user-123",
    "error": "API rate limit exceeded"
  }
}

💰 payment.received

Triggered when a payment is verified.

{
  "event": "payment.received",
  "timestamp": "2025-02-07T12:34:56.789Z",
  "data": {
    "agentId": "clx1234567890",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": 0.10,
    "token": "USDC",
    "chain": "base"
  }
}

🚀 agent.started

Triggered when an agent begins processing.

{
  "event": "agent.started",
  "timestamp": "2025-02-07T12:34:56.789Z",
  "data": {
    "agentId": "clx1234567890",
    "agentName": "My Trading Agent",
    "userId": "user-123"
  }
}

Setup Guide

1. Configure Your Webhook

Go to your agent settings page and add your webhook URL. Select which events you want to receive.

Go to My Agents

2. Test Your Webhook

Use the "Test Webhook" button in your agent settings to send a test event and verify your endpoint is working correctly.

3. Handle Webhook Events

Your server should respond with a 2xx status code to acknowledge receipt. We'll retry failed webhooks up to 3 times with exponential backoff.

// Example Node.js/Express handler
app.post('/webhook', express.json(), (req, res) => {
  const { event, timestamp, data } = req.body;

  // Verify webhook signature (recommended)
  // const signature = req.headers['x-webhook-signature'];

  switch (event) {
    case 'agent.completed':
      console.log('Agent completed:', data);
      // Handle completion
      break;
    case 'payment.received':
      console.log('Payment received:', data);
      // Update records
      break;
  }

  res.status(200).json({ received: true });
});

Integration Examples

Discord

Send notifications to a Discord channel when agents complete tasks.

// Use Discord webhook URL directly
// Format: https://discord.com/api/webhooks/{id}/{token}

// Transform Buildx402 webhook to Discord format
const discordPayload = {
  content: `✅ Agent ${data.agentName} completed!`,
  embeds: [{
    title: 'Agent Completed',
    description: data.result,
    color: 0x00ff00,
    timestamp: new Date().toISOString()
  }]
};

fetch(discordWebhookUrl, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(discordPayload)
});

Slack

Post updates to a Slack channel using Incoming Webhooks.

// Slack webhook format
const slackPayload = {
  text: `Agent ${data.agentName} completed!`,
  blocks: [
    {
      type: 'section',
      text: {
        type: 'mrkdwn',
        text: `*Agent Completed*\n${data.result}`
      }
    }
  ]
};

fetch(slackWebhookUrl, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(slackPayload)
});

Zapier / Make.com

Use "Webhooks by Zapier" or "Webhooks" module in Make.com to receive events and trigger workflows across 5000+ apps. Simply copy the webhook URL from Zapier/Make and paste it in your agent settings.

Best Practices

  • ✅
    Respond quickly - Process webhooks asynchronously and return 200 immediately
  • 🔒
    Verify signatures - Check the X-Webhook-Signature header to verify authenticity (coming soon)
  • 🔄
    Handle retries - We retry failed webhooks, so ensure your handler is idempotent
  • 📝
    Log events - Keep records of received webhooks for debugging
  • ⚡
    Use HTTPS - Always use secure URLs for webhook endpoints

Ready to Get Started?

Configure webhooks for your agents and start building powerful real-time integrations.

Configure WebhooksTry It Now