API Reference

Webhooks API

Manage webhook configurations, test deliveries, and inspect logs via the REST API.

This page covers the REST API for managing webhook configurations. For an in-depth guide on receiving and verifying webhook events, see the Webhooks Guide.

The Webhook object

{
  "id": 7,
  "name": "Production Webhook",
  "url": "https://yourapp.com/webhooks/skylightchat",
  "events": ["contact.created", "message.received", "booking.created"],
  "is_active": true,
  "created_at": "2026-03-01T10:00:00.000000Z",
  "updated_at": "2026-03-01T10:00:00.000000Z"
}

The webhook secret is only returned when you create or regenerate it. Store it securely — it is never returned again.

List webhooks

GET /api/v1/webhooks

curl https://dashboard.skylightchat.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_••••••••••••"

Response

Returns all webhooks for your account (not paginated).

{
  "success": true,
  "data": [
    {
      "id": 7,
      "name": "Production Webhook",
      "url": "https://yourapp.com/webhooks/skylightchat",
      "events": ["contact.created", "message.received"],
      "is_active": true,
      "delivery_logs_count": 42
    }
  ],
  "message": "Webhooks retrieved successfully."
}

Create a webhook

POST /api/v1/webhooks

Request body

{
  "name": "Production Webhook",
  "url": "https://yourapp.com/webhooks/skylightchat",
  "events": ["contact.created", "contact.updated", "message.received", "booking.created"]
}

Field	Required	Description
`name`	✓	Human-readable name
`url`	✓	HTTPS endpoint to receive events
`events`	✓	Array of event names to subscribe to

Response `201 Created`

{
  "success": true,
  "data": {
    "id": 7,
    "name": "Production Webhook",
    "url": "https://yourapp.com/webhooks/skylightchat",
    "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "events": ["contact.created", "message.received"],
    "is_active": true
  },
  "message": "Webhook created. Store the secret securely — it won't be shown again."
}

Get a webhook

GET /api/v1/webhooks/{id}

Update a webhook

PUT /api/v1/webhooks/{id}

{
  "events": ["contact.created", "booking.created", "booking.cancelled"],
  "is_active": false
}

Delete a webhook

DELETE /api/v1/webhooks/{id}

Returns 204 No Content.

Send a test event

POST /api/v1/webhooks/{id}/test

Sends a test webhook.test payload to the webhook URL, useful for verifying your endpoint is reachable and your signature verification works.

curl -X POST https://dashboard.skylightchat.com/api/v1/webhooks/7/test \
  -H "Authorization: Bearer sk_live_••••••••••••"

Test payload sent to your endpoint

{
  "event": "webhook.test",
  "delivery_id": "uuid-here",
  "timestamp": 1741093200,
  "data": {
    "message": "This is a test delivery from SkyLight Chat to verify your webhook endpoint.",
    "webhook_id": 7,
    "webhook_name": "Production Webhook"
  }
}

List delivery logs

GET /api/v1/webhooks/{id}/deliveries

Returns the delivery history for a webhook, including status and HTTP response codes.

Query parameters

Parameter	Type	Description
`page`	integer	Page number
`per_page`	integer	Items per page (max 100, default 25)
`status`	string	Filter: `pending`, `delivered`, `failed`

Response

{
  "success": true,
  "data": [
    {
      "id": 1024,
      "event_type": "contact.created",
      "delivery_id": "a1b2c3d4-e5f6-...",
      "attempt_number": 1,
      "response_status_code": 200,
      "status": "delivered",
      "delivered_at": "2026-03-04T12:00:05.000000Z",
      "created_at": "2026-03-04T12:00:00.000000Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 2, "per_page": 15, "total": 18 }
}

Regenerate secret

POST /api/v1/webhooks/{id}/regenerate-secret

Generates a new HMAC secret for the webhook. The old secret is immediately invalidated.

Response

{
  "success": true,
  "data": {
    "secret": "whsec_newxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "message": "Secret regenerated. Update your signature verification code."
}

Available events

GET /api/v1/webhooks/events

Returns all subscribable event names with descriptions:

{
  "success": true,
  "data": [
    { "event": "contact.created", "description": "A new contact is added" },
    { "event": "contact.updated", "description": "A contact's details are updated" },
    { "event": "contact.deleted", "description": "A contact is deleted" },
    { "event": "message.received", "description": "An inbound message is received from a contact" },
    { "event": "message.sent", "description": "An outbound message is sent to a contact" },
    { "event": "booking.created", "description": "A new booking is created" },
    { "event": "booking.updated", "description": "A booking is updated" },
    { "event": "booking.cancelled", "description": "A booking is cancelled" },
    { "event": "booking.completed", "description": "A booking is marked as completed" },
    { "event": "ticket.created", "description": "A new support ticket is opened" },
    { "event": "ticket.replied", "description": "A reply is added to a support ticket" }
  ],
  "message": "Available webhook events."
}

Orders

Create and manage customer orders with product items, track order status, and handle fulfillment.

Account

Read and update your account profile, subscription plan, and connected channel status.