Managing Webhooks

You can use the API to programmatically manage which webhook events are delivered to your endpoint — list available events, check which are enabled, and enable or disable individual events.

Webhook URL Required

Before using these endpoints, the Webhooks integration must be set up via the dashboard with a webhook URL. The API manages event subscriptions only — it does not set or change the webhook URL itself.

Required Scopes

• webhooks.read — List available and enabled webhook events
• webhooks.write — Enable or disable webhook events

List Available Events

Retrieve the full list of event types that can be subscribed to:

cURL

curl "https://app.sipsim.com/api/v2/webhooks/available" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"

response = requests.get(
    "https://app.sipsim.com/api/v2/webhooks/available",
    headers={"Authorization": f"Bearer {access_token}"}
)

events = response.json()["data"]
for event in events:
    print(event['event'])

JavaScript

const accessToken = 'YOUR_ACCESS_TOKEN';

const response = await fetch('https://app.sipsim.com/api/v2/webhooks/available', {
  headers: { 'Authorization': `Bearer ${accessToken}` }
});

const { data: events } = await response.json();
events.forEach(event => {
  console.log(event.event);
});

Response

{
  "status": 200,
  "request_id": "...",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": [
    { "event": "incoming_call_start" },
    { "event": "incoming_call_start_chain_member_call" },
    { "event": "incoming_call_end_chain_member_call" },
    { "event": "incoming_call_answer" },
    { "event": "incoming_call_end" },
    { "event": "outgoing_call_start" },
    { "event": "outgoing_call_answer" },
    { "event": "outgoing_call_end" },
    { "event": "voicemail" },
    { "event": "tags" },
    { "event": "speech" },
    { "event": "summary" },
    { "event": "sms" },
    { "event": "rating" }
  ]
}

List Enabled Events

Retrieve only the events your webhook is currently subscribed to:

cURL

curl "https://app.sipsim.com/api/v2/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"

response = requests.get(
    "https://app.sipsim.com/api/v2/webhooks",
    headers={"Authorization": f"Bearer {access_token}"}
)

events = response.json()["data"]
print(f"Subscribed to {len(events)} events:")
for event in events:
    print(f"  - {event['event']}")

JavaScript

const accessToken = 'YOUR_ACCESS_TOKEN';

const response = await fetch('https://app.sipsim.com/api/v2/webhooks', {
  headers: { 'Authorization': `Bearer ${accessToken}` }
});

const { data: events } = await response.json();
console.log(`Subscribed to ${events.length} events:`);
events.forEach(event => console.log(`  - ${event.event}`));

Response

{
  "status": 200,
  "request_id": "...",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": [
    { "event": "incoming_call_start" },
    { "event": "incoming_call_end" }
  ]
}

Enable an Event

Subscribe to a specific event by name:

cURL

curl -X POST "https://app.sipsim.com/api/v2/webhooks/outgoing_call_end" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"

response = requests.post(
    "https://app.sipsim.com/api/v2/webhooks/outgoing_call_end",
    headers={"Authorization": f"Bearer {access_token}"}
)

if response.status_code == 200:
    setting = response.json()["data"]
    print(f"Events now enabled: {setting['subscribed_events']}")
else:
    print(f"Error: {response.json()['errors']}")

JavaScript

const accessToken = 'YOUR_ACCESS_TOKEN';

const response = await fetch('https://app.sipsim.com/api/v2/webhooks/outgoing_call_end', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}` }
});

const data = await response.json();
if (response.ok) {
  console.log('Events now enabled:', data.data.subscribed_events);
} else {
  console.error('Error:', data.errors);
}

Response

The response includes the full current webhook setting:

{
  "status": 200,
  "request_id": "...",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "webhook_url": "https://example.com/webhooks/sipsim",
    "enabled": true,
    "subscribed_events": [
      "incoming_call_start",
      "incoming_call_end",
      "outgoing_call_end"
    ]
  }
}

Idempotent

Enabling an event that is already enabled has no effect — the call succeeds without duplicating the subscription.

Disable an Event

Unsubscribe from a specific event:

cURL

curl -X DELETE "https://app.sipsim.com/api/v2/webhooks/incoming_call_start" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"

response = requests.delete(
    "https://app.sipsim.com/api/v2/webhooks/incoming_call_start",
    headers={"Authorization": f"Bearer {access_token}"}
)

if response.status_code == 200:
    setting = response.json()["data"]
    print(f"Events still enabled: {setting['subscribed_events']}")

JavaScript

const accessToken = 'YOUR_ACCESS_TOKEN';

const response = await fetch('https://app.sipsim.com/api/v2/webhooks/incoming_call_start', {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${accessToken}` }
});

const data = await response.json();
if (response.ok) {
  console.log('Events still enabled:', data.data.subscribed_events);
}

Response Format

The enable and disable endpoints return the WebhookSetting object:

Field	Type	Description
webhook_url	string	Your configured webhook endpoint URL
enabled	boolean	Whether the webhook integration is active
subscribed_events	array	List of currently enabled event names

Error Handling

Webhook Integration Not Configured (404)

If the Webhooks integration has not been set up via the dashboard:

{
  "status": 404,
  "errors": ["Webhook integration not configured. Set a webhook URL via the dashboard first."],
  "request_id": "...",
  "timestamp": "2025-01-15T10:30:00Z",
  "path": "/api/v2/webhooks"
}

Solution: Set up the Webhooks integration from the dashboard first. The API cannot create the Webhooks integration — it can only manage event subscriptions for an existing one.

Unknown Event (400)

If you try to enable or disable an event name that doesn't exist:

{
  "status": 400,
  "errors": ["Unknown event 'invalid_event'. Use GET /api/v2/webhooks/available for the list of valid events."],
  "request_id": "...",
  "timestamp": "2025-01-15T10:30:00Z",
  "path": "/api/v2/webhooks/invalid_event"
}

Solution: Use the list available events endpoint to see valid event names.

Bulk Enable Example

To subscribe to all available events at once:

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"
headers = {"Authorization": f"Bearer {access_token}"}

available = requests.get(
    "https://app.sipsim.com/api/v2/webhooks/available",
    headers=headers
).json()["data"]

for event in available:
    requests.post(
        f"https://app.sipsim.com/api/v2/webhooks/{event['event']}",
        headers=headers
    )
    print(f"Enabled: {event['event']}")

print("All events enabled.")

JavaScript

const accessToken = 'YOUR_ACCESS_TOKEN';
const headers = { 'Authorization': `Bearer ${accessToken}` };

const { data: available } = await fetch(
  'https://app.sipsim.com/api/v2/webhooks/available',
  { headers }
).then(r => r.json());

for (const event of available) {
  await fetch(`https://app.sipsim.com/api/v2/webhooks/${event.event}`, {
    method: 'POST',
    headers
  });
  console.log(`Enabled: ${event.event}`);
}

console.log('All events enabled.');

Next Steps

• Webhooks Integration — Learn about webhook events, payload format, and signature verification
• Working with Calls — Track and filter your calls
• AI Features — Get transcriptions and summaries of your calls
• API Reference — Complete API documentation