Skip to main content

Webhooks API Reference

Complete reference for the Webhooks API endpoints.

List Webhooks​

Get all webhooks for your account.

GET /v1/webhooks

Query Parameters​

  • page (optional): Page number (default: 1)
  • perPage (optional): Items per page (default: 20, max: 100)

Response​

[
  {
    "id": "webhook_abc123",
    "userId": "user_xyz",
    "url": "https://example.com/webhooks/flow",
    "events": ["post.delivered", "post.failed"],
    "active": true,
    "createdAt": 1703123456000
  }
]

Create Webhook​

Create a new webhook.

POST /v1/webhooks

Request Body​

{
  "url": "https://example.com/webhooks/flow",
  "events": ["post.delivered", "post.failed"]
}

Response​

{
  "id": "webhook_abc123",
  "userId": "user_xyz",
  "url": "https://example.com/webhooks/flow",
  "events": ["post.delivered", "post.failed"],
  "secret": "whsec_abc123...",
  "active": true,
  "createdAt": 1703123456000
}

Important: Save the secret immediately - it's only shown once!

Get Webhook​

Get details for a specific webhook.

GET /v1/webhooks/:id

Response​

{
  "id": "webhook_abc123",
  "userId": "user_xyz",
  "url": "https://example.com/webhooks/flow",
  "events": ["post.delivered", "post.failed"],
  "active": true,
  "createdAt": 1703123456000
}

Update Webhook​

Update a webhook's configuration.

PATCH /v1/webhooks/:id

Request Body​

{
  "url": "https://new-url.com/webhooks/flow",
  "events": ["post.delivered", "post.failed", "post.created"],
  "active": false
}

All fields are optional.

Delete Webhook​

Delete a webhook.

DELETE /v1/webhooks/:id

Response​

{
  "message": "Webhook deleted successfully"
}

Get Delivery History​

Get delivery history for a webhook.

GET /v1/webhooks/:id/deliveries

Query Parameters​

  • page (optional): Page number (default: 1)
  • perPage (optional): Items per page (default: 20, max: 100)
  • status (optional): Filter by status (pending, delivered, failed)

Response​

[
  {
    "id": "delivery_abc123",
    "webhookId": "webhook_xyz",
    "eventId": "event_123",
    "eventType": "post.delivered",
    "status": "delivered",
    "attemptCount": 1,
    "responseCode": 200,
    "createdAt": 1703123456000,
    "deliveredAt": 1703123456100
  }
]

Test Webhook​

Send a test event to a webhook.

POST /v1/webhooks/:id/test

Response​

{
  "message": "Test event sent",
  "eventId": "event_test_123"
}

This sends a test event with event: "webhook.test" to verify your webhook configuration.

Webhook Events​

post.created​

Triggered when a new post is scheduled.

{
  "event": "post.created",
  "data": {
    "post_id": "post_abc123",
    "channel_id": "channel_xyz",
    "scheduled_for": 1703123456000,
    "status": "queued"
  },
  "timestamp": 1703123456000
}

post.delivered​

Triggered when a post is successfully published to all platforms.

{
  "event": "post.delivered",
  "data": {
    "post_id": "post_abc123",
    "channel_id": "channel_xyz",
    "delivered_at": 1703123456000
  },
  "timestamp": 1703123456000
}

post.failed​

Triggered when a post fails to publish.

{
  "event": "post.failed",
  "data": {
    "post_id": "post_abc123",
    "channel_id": "channel_xyz",
    "platform": "twitter",
    "error": "Rate limit exceeded",
    "will_retry": true
  },
  "timestamp": 1703123456000
}

post.blocked​

Triggered when a post is blocked (e.g., content policy violation).

{
  "event": "post.blocked",
  "data": {
    "post_id": "post_abc123",
    "channel_id": "channel_xyz",
    "reason": "Content policy violation",
    "platform": "twitter"
  },
  "timestamp": 1703123456000
}

channel.created​

Triggered when a new channel is created.

{
  "event": "channel.created",
  "data": {
    "channel_id": "channel_abc123",
    "name": "My Channel",
    "color": "#3B82F6"
  },
  "timestamp": 1703123456000
}

channel.updated​

Triggered when a channel is updated.

{
  "event": "channel.updated",
  "data": {
    "channel_id": "channel_abc123",
    "name": "Updated Name",
    "color": "#FF0000"
  },
  "timestamp": 1703123456000
}

Signature Verification​

Every webhook request includes a signature header:

Flow-Signature: t=1703123456,v1=abc123...

Verify signatures to ensure authenticity. See Webhooks Guide for implementation examples.

Retry Logic​

Flow automatically retries failed webhook deliveries with exponential backoff:

  • Attempt 1: Immediate
  • Attempt 2: 1 second delay
  • Attempt 3: 2 seconds delay
  • Attempt 4: 4 seconds delay
  • Attempt 5: 8 seconds delay
  • Attempt 6: 16 seconds delay
  • Attempt 7: 32 seconds delay

After 7 failed attempts, the delivery is marked as failed.

Best Practices​

  1. Always verify signatures - Never trust unverified requests
  2. Respond quickly - Your endpoint should respond within 5 seconds
  3. Handle idempotency - Same event may be delivered multiple times
  4. Use HTTPS - Webhook URLs must use HTTPS in production
  5. Monitor deliveries - Check delivery history regularly

See Webhooks Guide for detailed implementation examples and signature verification code.