webhooks

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.lost events
• analytics-insights — Pull analytics instead of waiting for events