Webhooks

https://api.voxburst.io/v1/webhooks

{
  "id": "evt_abc123",
  "type": "post.published",
  "createdAt": "2026-02-20T14:00:00Z",
  "data": {
    "id": "post_xyz789",
    "workspaceId": "ws_abc123",
    "content": "Hello from VoxBurst!",
    "status": "PARTIAL",
    "publishedAt": "2026-02-20T14:00:00Z",
    "platforms": [
      {
        "platform": "TWITTER",
        "status": "PUBLISHED",
        "platformPostId": "1234567890",
        "platformPostUrl": "https://x.com/user/status/1234567890",
        "publishedAt": "2026-02-20T14:00:01Z"
      },
      {
        "platform": "INSTAGRAM",
        "status": "FAILED",
        "error": {
          "code": "PUBLISH_ERROR",
          "message": "Media format not supported: image must be JPEG or PNG"
        }
      }
    ]
  }
}

X-VoxBurst-Signature: t=1707753600,v2=xxxxxxxxxxxxxxxx

import { createHmac, timingSafeEqual } from 'crypto'
 
function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const parts = Object.fromEntries(
    signature.split(',').map(p => p.split('=', 2) as [string, string])
  )
  const timestamp = parts['t']
  const signatureValue = parts['v2']
  if (!timestamp || !signatureValue) return false
 
  // Reject requests older than 5 minutes to prevent replay attacks
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (age > 300) return false
 
  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex')
 
  // Use timing-safe comparison to prevent timing attacks
  try {
    return timingSafeEqual(
      Buffer.from(expected, 'hex'),
      Buffer.from(signatureValue, 'hex')
    )
  } catch {
    return false
  }
}
 
// In your webhook handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-voxburst-signature'] as string
  const isValid = verifyWebhookSignature(
    req.rawBody,
    signature,
    process.env.WEBHOOK_SECRET!
  )
  if (!isValid) return res.status(401).send('Invalid signature')
 
  const event = req.body
  console.log(`Received event: ${event.type}`)
  res.status(200).send('OK')
})

import hmac
import hashlib
import time
 
def verify_webhook_signature(payload: str, signature: str, secret: str) -> bool:
    parts = dict(part.split("=", 1) for part in signature.split(","))
    timestamp = parts.get("t")
    sig = parts.get("v2")
    if not timestamp or not sig:
        return False
    # Reject requests older than 5 minutes to prevent replay attacks
    age = int(time.time()) - int(timestamp)
    if age > 300:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.{payload}".encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(sig, expected)

PENDING → DELIVERING → DELIVERED (success)
                    ↓ (non-2xx, timeout, or connection error)
                PENDING (scheduled for retry)
                    ↓ (after 3rd retry)
                  FAILED

curl -X PATCH https://api.voxburst.io/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

curl https://api.voxburst.io/v1/webhooks \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

{
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://yourapp.com/webhooks/voxburst",
      "events": ["post.published", "post.failed"],
      "enabled": true,
      "failureCount": 0,
      "consecutiveFailures": 0,
      "autoDisabledAt": null,
      "lastDeliveryAt": null,
      "createdAt": "2026-02-20T10:00:00Z",
      "updatedAt": "2026-02-20T10:00:00Z"
    }
  ]
}

curl -X POST https://api.voxburst.io/v1/webhooks \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/voxburst",
    "events": ["post.published", "post.failed"]
  }'

{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/voxburst",
  "events": ["post.published", "post.failed"],
  "enabled": true,
  "failureCount": 0,
  "consecutiveFailures": 0,
  "autoDisabledAt": null,
  "lastDeliveryAt": null,
  "createdAt": "2026-02-20T10:00:00Z",
  "updatedAt": "2026-02-20T10:00:00Z",
  "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

curl -X POST https://api.voxburst.io/v1/webhooks/wh_abc123/rotate-secret \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

{
  "success": true,
  "secret": "whsec_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
  "message": "Secret rotated successfully. Store the new secret securely - it will not be shown again."
}

curl https://api.voxburst.io/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

curl -X PATCH https://api.voxburst.io/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["post.published", "post.failed", "account.error"]
  }'

curl -X POST https://api.voxburst.io/v1/webhooks/test \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "webhookId": "wh_abc123" }'

curl -X DELETE https://api.voxburst.io/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

curl https://api.voxburst.io/v1/webhooks/wh_abc123/deliveries \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

{
  "data": [
    {
      "id": "del_xyz789",
      "webhookId": "wh_abc123",
      "eventType": "post.published",
      "url": "https://yourapp.com/webhooks/voxburst",
      "success": true,
      "retryCount": 0,
      "statusCode": 200,
      "latencyMs": 143,
      "responseBody": null,
      "error": null,
      "createdAt": "2026-04-09T12:00:05Z",
      "deliveredAt": "2026-04-09T12:00:05Z"
    }
  ],
  "pagination": { "hasMore": false }
}

curl "https://api.voxburst.io/v1/webhooks/wh_abc123/deliveries/stats?since=2026-04-01T00:00:00Z" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

{
  "data": {
    "total": 142,
    "delivered": 139,
    "failed": 3,
    "successRate": 97.9
  }
}

curl https://api.voxburst.io/v1/webhooks/wh_abc123/deliveries/del_xyz789 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

curl -X POST https://api.voxburst.io/v1/webhooks/wh_abc123/deliveries/del_xyz789/retry \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"