Webhooks

API-powered webhook system for receiving real-time event notifications from XActions.

Entry Points

API Usage

Create a webhook

POST /api/webhooks
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "events": ["operation.complete", "follower.lost", "follower.gained"],
  "secret": "your-signing-secret"
}

Test a webhook

POST /api/webhooks/:id/test
Authorization: Bearer <token>

Sends a test payload to the registered URL.

Supported Events

Payload Verification

Webhooks are signed with HMAC-SHA256 using your secret:

const signature = req.headers['x-xactions-signature'];
const expected = crypto.createHmac('sha256', secret)
  .update(JSON.stringify(req.body))
  .digest('hex');
const isValid = crypto.timingSafeEqual(
  Buffer.from(signature),
  Buffer.from(expected)
);

Notes

• Webhook deliveries are retried up to 3 times on failure (exponential backoff)
• Delivery logs are available via GET /api/webhooks/:id/deliveries
• Events are dispatched asynchronously from the Bull job queue

Related Skills

• xactions-mcp-server — AI agent integration alternative to webhooks
• follower-monitoring — Source of follower.gained / follower.lost events
• analytics-insights — Pull analytics instead of waiting for events