Webhook Setup

Webhooks allow your application to receive real-time notifications when events occur in Otesse. Instead of polling the API, your server receives HTTP POST requests when bookings are created, payments are processed, and more.

Registering a Webhook

Via Dashboard

Go to Settings > Integrations > Webhooks
Click Add Endpoint
Enter your webhook URL (must be HTTPS)
Select the events you want to subscribe to
Click Create

Via API

curl -X POST https://api.otesse.com/v1/webhooks \
  -H "Authorization: Bearer otesse_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/otesse",
    "events": [
      "booking.created",
      "booking.completed",
      "payment.succeeded",
      "payment.failed"
    ],
    "description": "Production booking and payment notifications"
  }'

Response

{
  "id": "wh_01HQ3K5M7N",
  "url": "https://yourapp.com/webhooks/otesse",
  "events": ["booking.created", "booking.completed", "payment.succeeded", "payment.failed"],
  "secret": "whsec_a1b2c3d4e5f6...",
  "status": "active",
  "created_at": "2026-02-26T10:00:00Z"
}

Save the secret value — you need it to verify webhook signatures.

Endpoint Requirements

Your webhook endpoint must:

Accept HTTPS POST requests
Respond with a 2xx status code within 30 seconds
Handle duplicate deliveries idempotently
Be publicly accessible (not localhost or private networks)

Testing Webhooks

Send a Test Event

From the webhook detail page, click Send Test to deliver a sample event to your endpoint. The test event has a test: true field so you can distinguish it from real events.

Local Development

For local development, use a tunneling service:

# Using ngrok
ngrok http 3000

# Register the ngrok URL as your webhook endpoint
# https://abc123.ngrok.io/webhooks/otesse

Managing Webhooks

List All Webhooks

GET /v1/webhooks

Update a Webhook

PATCH /v1/webhooks/:id

Delete a Webhook

DELETE /v1/webhooks/:id

View Delivery History

GET /v1/webhooks/:id/deliveries

Returns recent deliveries with status, response code, and response time. Failed deliveries include error details.