Webhooks
API-powered webhook system for receiving real-time event notifications from XActions.
Entry Points
| Goal | Route | Method |
|---|---|---|
| Create a webhook | POST /api/webhooks |
REST API |
| List webhooks | GET /api/webhooks |
REST API |
| Update a webhook | PATCH /api/webhooks/:id |
REST API |
| Delete a webhook | DELETE /api/webhooks/:id |
REST API |
| Test a webhook | POST /api/webhooks/:id/test |
REST API |
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
| Event | Triggered when |
|---|---|
operation.complete |
An automation job finishes successfully |
operation.failed |
An automation job fails |
follower.gained |
You gain a new follower |
follower.lost |
You lose a follower |
job.started |
A Bull queue job begins |
job.completed |
A Bull queue job completes |
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.lostevents - analytics-insights — Pull analytics instead of waiting for events