Webhooks API

Webhooks allow you to receive real-time notifications when users enter or exit segments. Cipres uses a transactional outbox pattern to ensure reliable delivery.

Events

Webhook Payload

When an event occurs, Cipres sends a POST request to your webhook URL with this payload:

{
  "event_type": "user_added",
  "timestamp": "2024-01-22T17:30:00Z",
  "pipeline_id": 3,
  "segment": {
    "id": "seg_abc123",
    "name": "Frustrated Users"
  },
  "user": {
    "id": "user_001",
    "score": 0.95
  }
}

Request Headers

Verifying Signatures

If you configure a secret when creating the webhook, Cipres will sign each request using HMAC-SHA256. Compute the HMAC-SHA256 of the raw request body using your webhook secret and compare it against the X-Webhook-Signature header to ensure requests are authentic.

API Endpoints

Create Webhook

{
  "url": "https://your-app.com/webhooks/cipres",
  "secret": "whsec_your_webhook_secret",
  "events": ["user_added", "user_removed"]
}

Responses

{
  "id": 1,
  "pipeline_id": 3,
  "url": "https://your-app.com/webhooks/cipres",
  "events": ["user_added", "user_removed"],
  "is_active": true,
  "created_at": "2024-01-22T17:00:00Z",
  "updated_at": "2024-01-22T17:00:00Z"
}

{
  "error": "URL is required"
}

{
  "error": "Pipeline not found"
}

List Webhooks

Returns all webhooks configured for the pipeline.

Responses

[
  {
    "id": 1,
    "pipeline_id": 3,
    "url": "https://your-app.com/webhooks/cipres",
    "events": ["user_added", "user_removed"],
    "is_active": true,
    "created_at": "2024-01-22T17:00:00Z",
    "updated_at": "2024-01-22T17:00:00Z"
  }
]

{
  "error": "Pipeline not found"
}

Get Webhook

Returns a single webhook by ID.

Update Webhook

{
  "url": "https://your-app.com/webhooks/cipres",
  "secret": "whsec_new_secret",
  "events": ["user_added", "user_removed"],
  "is_active": true
}

Delete Webhook

Permanently deletes a webhook. This action cannot be undone.

List Deliveries

View recent delivery attempts for a webhook. Useful for debugging. Accepts an optional limit query parameter (1-200, default: 50).

[
  {
    "id": 123,
    "event_id": 456,
    "webhook_id": 1,
    "status": "success",
    "status_code": 200,
    "response_body": "OK",
    "duration_ms": 145,
    "created_at": "2024-01-22T17:30:00Z"
  },
  {
    "id": 122,
    "event_id": 455,
    "webhook_id": 1,
    "status": "failed",
    "status_code": 500,
    "response_body": "Internal server error",
    "duration_ms": 2034,
    "created_at": "2024-01-22T17:25:00Z"
  }
]

Retry Policy

Failed deliveries are automatically retried up to 5 times with exponential backoff. A delivery is considered failed if:

• The endpoint returns a non-2xx status code
• The connection times out (10 second limit)
• The endpoint is unreachable

Best Practices

• Respond quickly — Return a 200 response within 10 seconds
• Process asynchronously — Queue webhook events for background processing
• Verify signatures — Always validate the X-Webhook-Signature header
• Handle duplicates — Use the X-Event-ID header for idempotency
• Use HTTPS — Webhook URLs must use HTTPS for security