Create a webhook endpoint (API key)
curl --request POST \ --url https://api.sipstack.com/api/v2/webhooks \ --header 'Content-Type: application/json' \ --header 'x-api-key: <x-api-key>' \ --data '{ "url": "https://example.com/sipstack-webhook", "events": [ "message.delivered", "message.failed" ] }'import requests
url = "https://api.sipstack.com/api/v2/webhooks"
payload = { "url": "https://example.com/sipstack-webhook", "events": ["message.delivered", "message.failed"]}headers = { "x-api-key": "<x-api-key>", "Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())const url = 'https://api.sipstack.com/api/v2/webhooks';const options = { method: 'POST', headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'}, body: '{"url":"https://example.com/sipstack-webhook","events":["message.delivered","message.failed"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}import axios from 'axios';
const options = { method: 'POST', url: 'https://api.sipstack.com/api/v2/webhooks', headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'}, data: { url: 'https://example.com/sipstack-webhook', events: ['message.delivered', 'message.failed'] }};
try { const { data } = await axios.request(options); console.log(data);} catch (error) { console.error(error);}Registers an endpoint URL for the given event types. The URL must be a public HTTPS address (localhost/private/reserved hosts are rejected). The signing secret is returned only in this response — store it now; it is never shown again. See the Webhooks guide for the event catalog.
This is the API-key (server-to-server) webhooks surface; the portal
admin-console equivalent lives under the Webhooks tag.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
Example
https://example.com/sipstack-webhookExample
[ "message.delivered", "message.failed"]Responses
Section titled “ Responses ”Endpoint created — data.secret is shown once.
object
The created endpoint — a compact subset of
ApiWebhookSummary (the RETURNING clause), plus the
one-time secret. failure_count, last_triggered_at, and
updated_at are NOT included on create; read them back from
GET /api/v2/webhooks.
object
HMAC signing secret — shown only here.
How to verify webhook deliveries — echoed by the API-key webhook endpoints.
object
Example
{ "message": "Webhook created. Store the secret now — it will not be shown again.", "data": { "url": "https://example.com/sipstack-webhook", "events": [ "message.delivered", "message.failed" ] }, "signature": { "header": "X-Webhook-Signature", "format": "sha256=<hex-hmac-sha256 of the raw request body, keyed by the endpoint secret>" }}Missing/invalid URL (including an SSRF-rejected host) or empty events array.
Inline error shape used by the messaging API and management endpoints.
object
Example
{ "success": false, "error": "Recipient phone number (to) is required"}Missing or invalid API key.
Inline error shape used by the messaging API and management endpoints.
object
Example
{ "success": false, "error": "Recipient phone number (to) is required"}Organization not provisioned for webhooks.
Inline error shape used by the messaging API and management endpoints.
object
Example
{ "success": false, "error": "Recipient phone number (to) is required"}Internal error.
Inline error shape used by the messaging API and management endpoints.
object
Example
{ "success": false, "error": "Recipient phone number (to) is required"}