API reference

Webhooks

8 endpoints in this group.

Lists webhooks

GET/api/v1/webhooks

Scope
read
SDK method
listWebhooks · list_webhooks
MCP tool
listWebhooksread-only

Example request

curl -X GET "https://hiboty.com/api/v1/webhooks" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "url": "https://example.com/hook",
      "description": "string",
      "events": [
        "message.received"
      ],
      "active": true,
      "failure_count": 1,
      "last_status": 1,
      "last_delivery_at": "2026-11-06T09:00:00.000Z",
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ]
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Creates a webhook

POST/api/v1/webhooks

The signing secret is returned only in this response. The address must be public https; localhost and private network addresses return 400. After 50 consecutive failed deliveries the webhook is turned off (active: false); turn it back on with enableWebhook or in the dashboard. Scope: write.

Scope
write
SDK method
createWebhook · create_webhook
MCP tool
createWebhookexternal effect

Body fields

NameTypeRequiredDescription
urluriyesPublic https address
descriptionstringnolen ≤ 120
eventsenum[]yesEvent names, e.g. message.receiveditems 1–30

Example request

curl -X POST "https://hiboty.com/api/v1/webhooks" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://ornek.com/hiboty-webhook","description":"CRM","events":["message.received","conversation.handoff"]}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://example.com/hook",
    "description": "string",
    "events": [
      "message.received"
    ],
    "active": true,
    "failure_count": 1,
    "last_status": 1,
    "last_delivery_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "secret": "string"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Webhook details

GET/api/v1/webhooks/{id}

The signing secret isn't returned. Needs admin permission. Scope: webhooks:read.

Scope
webhooks:read
SDK method
getWebhook · get_webhook
MCP tool
getWebhookread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X GET "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://example.com/hook",
    "description": "string",
    "events": [
      "message.received"
    ],
    "active": true,
    "failure_count": 1,
    "last_status": 1,
    "last_delivery_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Updates a webhook

PATCH/api/v1/webhooks/{id}

Only the fields you send change; the signing secret doesn't. The address must be public https. active: true resets the failure counter. Needs admin permission. Scope: webhooks:write.

Scope
webhooks:write
SDK method
updateWebhook · update_webhook
MCP tool
updateWebhookexternal effect

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Body fields

NameTypeRequiredDescription
urlurinolen ≤ 500
descriptionstringnolen ≤ 120
eventsenum[]noitems 1–30
activebooleanno

Example request

curl -X PATCH "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":["message.received","conversation.handoff"],"active":true}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://example.com/hook",
    "description": "string",
    "events": [
      "message.received"
    ],
    "active": true,
    "failure_count": 1,
    "last_status": 1,
    "last_delivery_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Deletes a webhook

DELETE/api/v1/webhooks/{id}

Scope
write
SDK method
deleteWebhook · delete_webhook
MCP tool
deleteWebhookirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesWebhook ID

Example request

curl -X DELETE "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Turns a disabled webhook back on

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

Turns on a webhook disabled after 50 consecutive failed deliveries and resets its failure counter. Scope: write.

Scope
write
SDK method
enableWebhook · enable_webhook
MCP tool
enableWebhookexternal effect

Parameters

NameTypeRequiredDescription
idpathuuidyesWebhook ID

Example request

curl -X POST "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/enable" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://example.com/hook",
    "description": "string",
    "events": [
      "message.received"
    ],
    "active": true,
    "failure_count": 1,
    "last_status": 1,
    "last_delivery_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Lists delivery history

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

The event payload (it can carry personal data) isn't returned; only the status, attempts and error are. Needs admin permission. Scope: webhooks:read.

Scope
webhooks:read
SDK method
listWebhookDeliveries · list_webhook_deliveries
MCP tool
listWebhookDeliveriesread-only

Paginated

Parameters

NameTypeRequiredDescription
idpathuuidyesID
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque)

Example request

curl -X GET "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/deliveries?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "event": "message.received",
      "status": "pending",
      "attempts": 1,
      "response_status": 1,
      "error": "string",
      "delivered_at": "2026-11-06T09:00:00.000Z",
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Sends a test event (ping)

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

A real request goes to the address (private network addresses are rejected). A disabled webhook returns 409 webhook_inactive. Needs admin permission. Scope: webhooks:write.

Scope
webhooks:write
SDK method
testWebhook · test_webhook
MCP tool
testWebhookexternal effect

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X POST "https://hiboty.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/test" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "delivered": true,
    "status": 1
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.webhook_inactive
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.