Retrieve webhook

Retrieves configuration details for the authenticated user account's currently active webhook subscription. 

GET /api/v2/webhook

Table of contents

Endpoint summary

Property Value
HTTP method GET
Endpoint path /api/v2/webhook
Authentication Authorization: Bearer <api_key> or Authorization: Basic <base64(username:password)>
Success status code 200 OK

Note: For security reasons, the shared signing secret is only returned upon initial registration (POST /api/v2/webhook) or replacement (PUT /api/v2/webhook) and is omitted from GET /api/v2/webhook responses. If the signing secret is lost, replace the webhook using PUT /api/v2/webhook to generate a new secret.

Request

Request headers

Header Required Description
Authorization Yes Credentials identifying the user account context (Bearer <api_key> or Basic <credentials>).

Response

200 OK

Returns a WebhookResponse object describing the active webhook subscription (with secret omitted).

Field Type Description
webhookId string (UUID) Unique internal identifier of the webhook configuration.
url string Registered target HTTP or HTTPS notification URL.
events string[] Array of subscribed event types ("message.received", "message.status.updated").

Error responses

When authentication fails or no webhook subscription is currently configured for the user account, the API returns a structured ApiErrorResponse object.

Common error status codes:

Status code Condition Description
401 Unauthorized Missing or invalid credentials Authentication credentials were not provided or could not be resolved to an active user.
404 Not Found No webhook configured No active webhook subscription exists for the authenticated user account.

Error schema (ApiErrorResponse):

Field Type Description
error.code integer HTTP status code (e.g., 401, 404).
error.description string Explanation of the specific error condition.
error.action string Recommended action to resolve the error.
error.timestamp string (ISO 8601) Timestamp when the error occurred.

Examples

1. Retrieve the current webhook configuration

Queries the active webhook configuration for the authenticated user account.

Request: 

GET /api/v2/webhook HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>

Response (200 OK): 

{
  "webhookId": "7f8a9b0c-1d2e-3f4a-5b6c-7d8e9f0a1b2c",
  "url": "https://client.example.com/api/sms/inbound",
  "events": [
    "message.received",
    "message.status.updated"
  ]
}

2. Error: No webhook configured (404 Not Found)

Returned when attempting to query the webhook configuration when no active subscription exists.

Response (404 Not Found): 

{
  "error": {
    "code": 404,
    "description": "No webhook is currently configured for this account.",
    "action": "Register a webhook using POST /api/v2/webhook or PUT /api/v2/webhook.",
    "timestamp": "2026-10-21T10:21:00+02:00"
  }
}

More information