Webhooks

Endpointhttps://api.neuratel.ai

Event delivery and webhook subscriptions for real-time integrations.

List webhook subscriptions

GET

https://api.neuratel.ai

/v1/webhooks

List all webhook subscriptions for your organization

List webhook subscriptions › query Parameters

skip

integer · min: 0

Number of records to skip for pagination. Defaults to 0.

Default: 0

limit

integer · min: 1 · max: 1000

Maximum number of records to return. Defaults to 100. Max 1000.

Default: 100

is_active

Filter by active status

List webhook subscriptions › Responses

Successful Response

Paginated list of webhooks. Standardized pagination format: - results: List of webhooks - metadata: Pagination info (skip, limit, total, has_more, count)

object[] · required

object · required

Pagination metadata in API responses.

GET/v1/webhooks

curl --request GET \
  --url https://api.neuratel.ai/v1/webhooks

shell

Example Responses

{
  "results": [
    {
      "auth_header": "X-Api-Key",
      "created_at": "2024-01-01T00:00:00Z",
      "description": "Receive call lifecycle events",
      "events": [
        "call.started",
        "call.ended"
      ],
      "failure_count": 0,
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "is_active": true,
      "last_success_at": "2024-01-15T10:30:00Z",
      "max_retries": 3,
      "name": "Call Events Webhook",
      "organization_id": "123e4567-e89b-12d3-a456-426614174001",
      "timeout_seconds": 30,
      "updated_at": "2024-01-15T10:30:00Z",
      "url": "https://api.example.com/webhooks/neuratel"
    }
  ],
  "metadata": {
    "count": 100,
    "has_more": true,
    "limit": 100,
    "skip": 0,
    "total": 250
  }
}

json

application/json

Create webhook subscription

POST

https://api.neuratel.ai

/v1/webhooks

Create a new webhook subscription to receive event notifications.

Code
The response will include a `secret` which is used to sign all webhook
payloads with HMAC-SHA256. **Store this secret securely - it will only
be shown once!**

Use the signature to verify that webhook requests are genuinely from Neuratel:
```python
import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)
```

Create webhook subscription › Request Body

Create a new webhook subscription

name

string · minLength: 1 · maxLength: 255 · required

Human-readable name for the webhook

url

string · required

HTTPS endpoint URL to receive webhook events

Optional description

events

string[]

List of event types to subscribe to. Empty = all events

Enum values:

call.started

call.ended

call.ringing

call.answered

call.failed

call.transferred

transcript.partial

transcript.final

Optional custom header name for authentication (e.g., 'X-Api-Key')

Value for the auth header

timeout_seconds

integer · min: 1 · max: 60

Request timeout in seconds (1-60)

Default: 30

max_retries

integer · min: 0 · max: 5

Maximum retry attempts on failure (0-5)

Default: 3

is_active

boolean

Whether the webhook is active

Default: true

Create webhook subscription › Responses

Successful Response

Response when creating a webhook - includes secret

id

string · uuid · required

Unique webhook identifier

organization_id

string · uuid · required

Organization this webhook belongs to

name

string · required

Display name for this webhook

url

string · required

HTTPS endpoint that receives event payloads

events

string[] · required

Event types this webhook subscribes to

is_active

boolean · required

Whether this webhook is enabled. Auto-disabled after 10 consecutive delivery failures

timeout_seconds

integer · required

Request timeout per delivery attempt in seconds

max_retries

integer · required

Maximum retry attempts on delivery failure

failure_count

integer · required

Consecutive delivery failures since last success

created_at

string · date-time · required

Creation timestamp

updated_at

string · date-time · required

Last update timestamp

secret

string · required

HMAC secret for validating webhook signatures. Store securely - only shown once!

Optional description

Custom header name sent with each request (e.g. X-Api-Key)

Reason this webhook was auto-disabled, if applicable

Timestamp of last successful delivery

Timestamp of last failed delivery attempt

POST/v1/webhooks

curl --request POST \
  --url https://api.neuratel.ai/v1/webhooks \
  --header 'Content-Type: application/json' \
  --data '
{
  "auth_header": "X-Api-Key",
  "auth_value": "your-secret-key",
  "description": "Receive call lifecycle events",
  "events": [
    "call.started",
    "call.ended",
    "transcript.ready"
  ],
  "max_retries": 3,
  "name": "Call Events Webhook",
  "timeout_seconds": 30,
  "url": "https://api.example.com/webhooks/neuratel"
}
'

shell

Example Request Body

{
  "auth_header": "X-Api-Key",
  "auth_value": "your-secret-key",
  "description": "Receive call lifecycle events",
  "events": [
    "call.started",
    "call.ended",
    "transcript.ready"
  ],
  "max_retries": 3,
  "name": "Call Events Webhook",
  "timeout_seconds": 30,
  "url": "https://api.example.com/webhooks/neuratel"
}

json

Example Responses

{
  "auth_header": "X-Api-Key",
  "created_at": "2024-01-01T00:00:00Z",
  "description": "Receive call lifecycle events",
  "events": [
    "call.started",
    "call.ended"
  ],
  "failure_count": 0,
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "is_active": true,
  "last_success_at": "2024-01-15T10:30:00Z",
  "max_retries": 3,
  "name": "Call Events Webhook",
  "organization_id": "123e4567-e89b-12d3-a456-426614174001",
  "timeout_seconds": 30,
  "updated_at": "2024-01-15T10:30:00Z",
  "url": "https://api.example.com/webhooks/neuratel"
}

json

application/json

List available webhook events

GET

https://api.neuratel.ai

/v1/webhooks/events

Get all available webhook event types and their descriptions

List available webhook events › Responses

200

Successful Response

No data returned

Get webhook details

GET

https://api.neuratel.ai

/v1/webhooks/{webhook_id}

Get details of a specific webhook subscription

Get webhook details › path Parameters

webhook_id

string · uuid · required

Webhook subscription ID

Get webhook details › Responses

Successful Response

Webhook subscription response

id

string · uuid · required

Unique webhook identifier

organization_id

string · uuid · required

Organization this webhook belongs to

name

string · required

Display name for this webhook

url

string · required

HTTPS endpoint that receives event payloads

events

string[] · required

Event types this webhook subscribes to

is_active

boolean · required

Whether this webhook is enabled. Auto-disabled after 10 consecutive delivery failures

timeout_seconds

integer · required

Request timeout per delivery attempt in seconds

max_retries

integer · required

Maximum retry attempts on delivery failure

failure_count

integer · required

Consecutive delivery failures since last success

created_at

string · date-time · required

Creation timestamp

updated_at

string · date-time · required

Last update timestamp

Optional description

Custom header name sent with each request (e.g. X-Api-Key)

Reason this webhook was auto-disabled, if applicable

Timestamp of last successful delivery

Timestamp of last failed delivery attempt

Delete webhook

DELETE

https://api.neuratel.ai

/v1/webhooks/{webhook_id}

Permanently delete a webhook subscription

Delete webhook › path Parameters

webhook_id

string · uuid · required

Webhook subscription ID

Delete webhook › Responses

Successful Response

No data returned

Update webhook

PATCH

https://api.neuratel.ai

/v1/webhooks/{webhook_id}

Update a webhook subscription. Only provided fields will be updated.

Update webhook › path Parameters

webhook_id

string · uuid · required

Webhook subscription ID

Update webhook › Request Body

Update an existing webhook subscription

Update webhook › Responses

Successful Response

Webhook subscription response

id

string · uuid · required

Unique webhook identifier

organization_id

string · uuid · required

Organization this webhook belongs to

name

string · required

Display name for this webhook

url

string · required

HTTPS endpoint that receives event payloads

events

string[] · required

Event types this webhook subscribes to

is_active

boolean · required

Whether this webhook is enabled. Auto-disabled after 10 consecutive delivery failures

timeout_seconds

integer · required

Request timeout per delivery attempt in seconds

max_retries

integer · required

Maximum retry attempts on delivery failure

failure_count

integer · required

Consecutive delivery failures since last success

created_at

string · date-time · required

Creation timestamp

updated_at

string · date-time · required

Last update timestamp

Optional description

Custom header name sent with each request (e.g. X-Api-Key)

Reason this webhook was auto-disabled, if applicable

Timestamp of last successful delivery

Timestamp of last failed delivery attempt

PATCH/v1/webhooks/{webhook_id}

curl --request PATCH \
  --url https://api.neuratel.ai/v1/webhooks/:webhook_id \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "string",
  "description": "string",
  "url": "string",
  "events": [
    "call.started"
  ],
  "auth_header": "string",
  "auth_value": "string",
  "timeout_seconds": 1,
  "max_retries": 0,
  "is_active": true
}
'

shell

Example Request Body

{
  "name": "string",
  "description": "string",
  "url": "string",
  "events": [
    "call.started"
  ],
  "auth_header": "string",
  "auth_value": "string",
  "timeout_seconds": 1,
  "max_retries": 0,
  "is_active": true
}

json

Example Responses

{
  "auth_header": "X-Api-Key",
  "created_at": "2024-01-01T00:00:00Z",
  "description": "Receive call lifecycle events",
  "events": [
    "call.started",
    "call.ended"
  ],
  "failure_count": 0,
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "is_active": true,
  "last_success_at": "2024-01-15T10:30:00Z",
  "max_retries": 3,
  "name": "Call Events Webhook",
  "organization_id": "123e4567-e89b-12d3-a456-426614174001",
  "timeout_seconds": 30,
  "updated_at": "2024-01-15T10:30:00Z",
  "url": "https://api.example.com/webhooks/neuratel"
}

json

application/json

Test webhook

POST

https://api.neuratel.ai

/v1/webhooks/{webhook_id}/test

Send a test event to the webhook URL. This will deliver a sample payload signed with the webhook's secret, allowing you to verify your endpoint is correctly configured.

Test webhook › path Parameters

webhook_id

string · uuid · required

Webhook subscription ID

Test webhook › Request Body

Test a webhook with a sample payload

event_type

string · enum

Event type to simulate

Enum values:

call.started

call.ended

call.ringing

call.answered

call.failed

call.transferred

transcript.partial

transcript.final

Default: call.started

Test webhook › Responses

Successful Response

Result of webhook test

success

boolean · required

required

duration_ms

integer · required

Rotate webhook secret

POST

https://api.neuratel.ai

/v1/webhooks/{webhook_id}/secret/rotate

Generate a new signing secret for the webhook. The old secret will be immediately invalidated. Store the new secret securely!

Rotate webhook secret › path Parameters

webhook_id

string · uuid · required

Webhook subscription ID

Rotate webhook secret › Responses

Successful Response

secret

string · required

message

string · required

Get delivery logs

GET

https://api.neuratel.ai

/v1/webhooks/{webhook_id}/logs

Get delivery attempt logs for a webhook subscription

Get delivery logs › path Parameters

webhook_id

string · uuid · required

Webhook subscription ID

Get delivery logs › query Parameters

skip

integer · min: 0

Number of records to skip for pagination. Defaults to 0.

Default: 0

limit

integer · min: 1 · max: 1000

Maximum number of records to return. Defaults to 100. Max 1000.

Default: 100

success_only

Filter by success status

Get delivery logs › Responses

Successful Response

Paginated delivery logs

object[] · required

total

integer · required

skip

integer · required

limit

integer · required

Status Organizations

Neuratel API

Webhooks

Endpointhttps://api.neuratel.ai

Event delivery and webhook subscriptions for real-time integrations.

List webhook subscriptions

GET

https://api.neuratel.ai

/v1/webhooks

List all webhook subscriptions for your organization

List webhook subscriptions › query Parameters

skip

integer · min: 0

Number of records to skip for pagination. Defaults to 0.

Default: 0

limit

integer · min: 1 · max: 1000

Maximum number of records to return. Defaults to 100. Max 1000.

Default: 100

is_active

Filter by active status

List webhook subscriptions › Responses

Successful Response

Paginated list of webhooks. Standardized pagination format: - results: List of webhooks - metadata: Pagination info (skip, limit, total, has_more, count)

object[] · required

object · required

Pagination metadata in API responses.

GET/v1/webhooks

curl --request GET \
  --url https://api.neuratel.ai/v1/webhooks

shell

Example Responses

{
  "results": [
    {
      "auth_header": "X-Api-Key",
      "created_at": "2024-01-01T00:00:00Z",
      "description": "Receive call lifecycle events",
      "events": [
        "call.started",
        "call.ended"
      ],
      "failure_count": 0,
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "is_active": true,
      "last_success_at": "2024-01-15T10:30:00Z",
      "max_retries": 3,
      "name": "Call Events Webhook",
      "organization_id": "123e4567-e89b-12d3-a456-426614174001",
      "timeout_seconds": 30,
      "updated_at": "2024-01-15T10:30:00Z",
      "url": "https://api.example.com/webhooks/neuratel"
    }
  ],
  "metadata": {
    "count": 100,
    "has_more": true,
    "limit": 100,
    "skip": 0,
    "total": 250
  }
}

json

application/json

Create webhook subscription

POST

https://api.neuratel.ai

/v1/webhooks

Create a new webhook subscription to receive event notifications.

Code
The response will include a `secret` which is used to sign all webhook
payloads with HMAC-SHA256. **Store this secret securely - it will only
be shown once!**

Use the signature to verify that webhook requests are genuinely from Neuratel:
```python
import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)
```

Create webhook subscription › Request Body

Create a new webhook subscription

name

string · minLength: 1 · maxLength: 255 · required

Human-readable name for the webhook

url

string · required

HTTPS endpoint URL to receive webhook events

Optional description

events

string[]

List of event types to subscribe to. Empty = all events

Enum values:

call.started

call.ended

call.ringing

call.answered

call.failed

call.transferred

transcript.partial

transcript.final

Optional custom header name for authentication (e.g., 'X-Api-Key')

Value for the auth header

timeout_seconds

integer · min: 1 · max: 60

Request timeout in seconds (1-60)

Default: 30

max_retries

integer · min: 0 · max: 5

Maximum retry attempts on failure (0-5)

Default: 3

is_active

boolean

Whether the webhook is active

Default: true

Create webhook subscription › Responses

Successful Response

Response when creating a webhook - includes secret

id

string · uuid · required

Unique webhook identifier

organization_id

string · uuid · required

Organization this webhook belongs to

name

string · required

Display name for this webhook

url

string · required

HTTPS endpoint that receives event payloads

events

string[] · required

Event types this webhook subscribes to

is_active

boolean · required

Whether this webhook is enabled. Auto-disabled after 10 consecutive delivery failures

timeout_seconds

integer · required

Request timeout per delivery attempt in seconds

max_retries

integer · required

Maximum retry attempts on delivery failure

failure_count

integer · required

Consecutive delivery failures since last success

created_at

string · date-time · required

Creation timestamp

updated_at

string · date-time · required

Last update timestamp

secret

string · required

HMAC secret for validating webhook signatures. Store securely - only shown once!

Optional description

Custom header name sent with each request (e.g. X-Api-Key)

Reason this webhook was auto-disabled, if applicable

Timestamp of last successful delivery

Timestamp of last failed delivery attempt

POST/v1/webhooks

curl --request POST \
  --url https://api.neuratel.ai/v1/webhooks \
  --header 'Content-Type: application/json' \
  --data '
{
  "auth_header": "X-Api-Key",
  "auth_value": "your-secret-key",
  "description": "Receive call lifecycle events",
  "events": [
    "call.started",
    "call.ended",
    "transcript.ready"
  ],
  "max_retries": 3,
  "name": "Call Events Webhook",
  "timeout_seconds": 30,
  "url": "https://api.example.com/webhooks/neuratel"
}
'

shell

Example Request Body

{
  "auth_header": "X-Api-Key",
  "auth_value": "your-secret-key",
  "description": "Receive call lifecycle events",
  "events": [
    "call.started",
    "call.ended",
    "transcript.ready"
  ],
  "max_retries": 3,
  "name": "Call Events Webhook",
  "timeout_seconds": 30,
  "url": "https://api.example.com/webhooks/neuratel"
}

json

Example Responses

{
  "auth_header": "X-Api-Key",
  "created_at": "2024-01-01T00:00:00Z",
  "description": "Receive call lifecycle events",
  "events": [
    "call.started",
    "call.ended"
  ],
  "failure_count": 0,
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "is_active": true,
  "last_success_at": "2024-01-15T10:30:00Z",
  "max_retries": 3,
  "name": "Call Events Webhook",
  "organization_id": "123e4567-e89b-12d3-a456-426614174001",
  "timeout_seconds": 30,
  "updated_at": "2024-01-15T10:30:00Z",
  "url": "https://api.example.com/webhooks/neuratel"
}

json

application/json

List available webhook events

GET

https://api.neuratel.ai

/v1/webhooks/events

Get all available webhook event types and their descriptions

List available webhook events › Responses

200

Successful Response

No data returned

Get webhook details

GET

https://api.neuratel.ai

/v1/webhooks/{webhook_id}

Get details of a specific webhook subscription

Get webhook details › path Parameters

webhook_id

string · uuid · required

Webhook subscription ID

Get webhook details › Responses

Successful Response

Webhook subscription response

id

string · uuid · required

Unique webhook identifier

organization_id

string · uuid · required

Organization this webhook belongs to

name

string · required

Display name for this webhook

url

string · required

HTTPS endpoint that receives event payloads

events

string[] · required

Event types this webhook subscribes to

is_active

boolean · required

Whether this webhook is enabled. Auto-disabled after 10 consecutive delivery failures

timeout_seconds

integer · required

Request timeout per delivery attempt in seconds

max_retries

integer · required

Maximum retry attempts on delivery failure

failure_count

integer · required

Consecutive delivery failures since last success

created_at

string · date-time · required

Creation timestamp

updated_at

string · date-time · required

Last update timestamp

Optional description

Custom header name sent with each request (e.g. X-Api-Key)

Reason this webhook was auto-disabled, if applicable

Timestamp of last successful delivery

Timestamp of last failed delivery attempt

Delete webhook

DELETE

https://api.neuratel.ai

/v1/webhooks/{webhook_id}

Permanently delete a webhook subscription

Delete webhook › path Parameters

webhook_id

string · uuid · required

Webhook subscription ID

Delete webhook › Responses

Successful Response

No data returned

Update webhook

PATCH

https://api.neuratel.ai

/v1/webhooks/{webhook_id}

Update a webhook subscription. Only provided fields will be updated.

Update webhook › path Parameters

webhook_id

string · uuid · required

Webhook subscription ID

Update webhook › Request Body

Update an existing webhook subscription

Update webhook › Responses

Successful Response

Webhook subscription response

id

string · uuid · required

Unique webhook identifier

organization_id

string · uuid · required

Organization this webhook belongs to

name

string · required

Display name for this webhook

url

string · required

HTTPS endpoint that receives event payloads

events

string[] · required

Event types this webhook subscribes to

is_active

boolean · required

Whether this webhook is enabled. Auto-disabled after 10 consecutive delivery failures

timeout_seconds

integer · required

Request timeout per delivery attempt in seconds

max_retries

integer · required

Maximum retry attempts on delivery failure

failure_count

integer · required

Consecutive delivery failures since last success

created_at

string · date-time · required

Creation timestamp

updated_at

string · date-time · required

Last update timestamp

Optional description

Custom header name sent with each request (e.g. X-Api-Key)

Reason this webhook was auto-disabled, if applicable

Timestamp of last successful delivery

Timestamp of last failed delivery attempt

PATCH/v1/webhooks/{webhook_id}

curl --request PATCH \
  --url https://api.neuratel.ai/v1/webhooks/:webhook_id \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "string",
  "description": "string",
  "url": "string",
  "events": [
    "call.started"
  ],
  "auth_header": "string",
  "auth_value": "string",
  "timeout_seconds": 1,
  "max_retries": 0,
  "is_active": true
}
'

shell

Example Request Body

{
  "name": "string",
  "description": "string",
  "url": "string",
  "events": [
    "call.started"
  ],
  "auth_header": "string",
  "auth_value": "string",
  "timeout_seconds": 1,
  "max_retries": 0,
  "is_active": true
}

json

Example Responses

{
  "auth_header": "X-Api-Key",
  "created_at": "2024-01-01T00:00:00Z",
  "description": "Receive call lifecycle events",
  "events": [
    "call.started",
    "call.ended"
  ],
  "failure_count": 0,
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "is_active": true,
  "last_success_at": "2024-01-15T10:30:00Z",
  "max_retries": 3,
  "name": "Call Events Webhook",
  "organization_id": "123e4567-e89b-12d3-a456-426614174001",
  "timeout_seconds": 30,
  "updated_at": "2024-01-15T10:30:00Z",
  "url": "https://api.example.com/webhooks/neuratel"
}

json

application/json

Test webhook

POST

https://api.neuratel.ai

/v1/webhooks/{webhook_id}/test

Send a test event to the webhook URL. This will deliver a sample payload signed with the webhook's secret, allowing you to verify your endpoint is correctly configured.

Test webhook › path Parameters

webhook_id

string · uuid · required

Webhook subscription ID

Test webhook › Request Body

Test a webhook with a sample payload

event_type

string · enum

Event type to simulate

Enum values:

call.started

call.ended

call.ringing

call.answered

call.failed

call.transferred

transcript.partial

transcript.final

Default: call.started

Test webhook › Responses

Successful Response

Result of webhook test

success

boolean · required

required

duration_ms

integer · required

Rotate webhook secret

POST

https://api.neuratel.ai

/v1/webhooks/{webhook_id}/secret/rotate

Generate a new signing secret for the webhook. The old secret will be immediately invalidated. Store the new secret securely!

Rotate webhook secret › path Parameters

webhook_id

string · uuid · required

Webhook subscription ID

Rotate webhook secret › Responses

Successful Response

secret

string · required

message

string · required

Get delivery logs

GET

https://api.neuratel.ai

/v1/webhooks/{webhook_id}/logs

Get delivery attempt logs for a webhook subscription

Get delivery logs › path Parameters

webhook_id

string · uuid · required

Webhook subscription ID

Get delivery logs › query Parameters

skip

integer · min: 0

Number of records to skip for pagination. Defaults to 0.

Default: 0

limit

integer · min: 1 · max: 1000

Maximum number of records to return. Defaults to 100. Max 1000.

Default: 100

success_only

Filter by success status

Get delivery logs › Responses

Successful Response

Paginated delivery logs

object[] · required

total

integer · required

skip

integer · required

limit

integer · required

Status Organizations