Webhook

Overview

Webhooks, a robust feature offered by VoIPBIN, empower users to receive real-time event data for their calls and associated resources directly on their servers. By establishing custom endpoints, users can seamlessly configure their servers to receive timely notifications and updates related to VoIPBIN resources, thereby enhancing control, customization, and real-time visibility within their communication workflows.

Notification Mechanism

Webhook events act as notifications sent by VoIPBIN, triggering when specific events or actions unfold within the system, such as call events, message events, or changes to resources like queues or agents. Configured webhook endpoints receive these events, ensuring users promptly receive pertinent data related to their VoIPBIN resources.

_images/webhook_overview_notification.png

Types of Webhooks

VoIPBIN tailors webhooks for each resource type, ensuring users receive granular progress and updates for various events. This resource-specific approach allows users to monitor their VoIPBIN resources with precision, obtaining notifications and data tailored to each resource type. For instance, call-specific webhook events furnish details on call status, duration, and caller ID, while message-specific events offer insights into SMS or MMS messages, including content, sender ID, and delivery status.

Custom Endpoints

To harness webhooks, users must configure custom webhook endpoints on their servers. These endpoints, serving as URLs, dictate where VoIPBIN transmits webhook events. Upon an event occurrence, VoIPBIN initiates an HTTP request to the configured endpoint, incorporating relevant data in the payload. This empowers users to process and respond to events according to their unique requirements.

Benefits of Webhooks

Webhooks deliver a range of advantages for VoIPBIN users:

Real-Time Updates: Offering immediate event notifications, webhooks keep users abreast of real-time changes to their VoIPBIN resources.
Customization: Users can tailor webhook endpoints and process data as per their specific needs, facilitating the creation of customized workflows and integrations.
Automated Actions: Webhooks enable users to automate actions based on event data, such as record updates, notifications, or the initiation of additional processes.
Enhanced Monitoring: Providing a proactive monitoring solution, webhooks empower users to track and respond promptly to changes within the VoIPBIN system, ensuring informed decision-making.

Webhook

activeflow_created

The notification message for the activeflow create.

{
    "type": "activeflow_created",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of activeflow. See detail here.

Example

{
    "type": "activeflow_created",
    "data": {
        "id": "74ac5405-7c70-4184-9388-1c9f8f8ce25f",
        "flow_id": "d157ce07-0360-4cad-9007-c8ab89fccf9c",
        "customer_id": "00000000-0000-0000-0000-000000000000",
        "reference_type": "call",
        "reference_id": "5371e9db-d035-4db6-a8d6-0994d33e744e",
        "current_action": {
            "id": "00000000-0000-0000-0000-000000000001",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": ""
        },
        "forward_action_id": "00000000-0000-0000-0000-000000000000",
        "actions": [
            {
                "id": "df25724f-e308-4c89-9325-cf56cd09249e",
                "next_id": "00000000-0000-0000-0000-000000000000",
                "type": "answer"
            },
            {
                "id": "2e7ec294-fc66-4039-8446-6590b82ed54f",
                "next_id": "00000000-0000-0000-0000-000000000000",
                "type": "talk",
                "option": {
                    "text": "hello. welcome to voipbin. This is test message. Please enjoy the voipbin's service. thank you.",
                    "gender": "female",
                    "language": "en-US"
                }
            }
        ],
        "tm_create": "2022-04-11 00:23:54.724620",
        "tm_update": "2022-04-11 00:23:54.724620",
        "tm_delete": "9999-01-01 00:00:00.000000"
    }
}

activeflow_updated

The notification message for the activeflow update.

{
    "type": "activeflow_updated",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of activeflow. See detail here.

Example

{
    "type": "activeflow_updated",
    "data": {
        "id": "74ac5405-7c70-4184-9388-1c9f8f8ce25f",
        "flow_id": "d157ce07-0360-4cad-9007-c8ab89fccf9c",
        "customer_id": "00000000-0000-0000-0000-000000000000",
        "reference_type": "call",
        "reference_id": "5371e9db-d035-4db6-a8d6-0994d33e744e",
        "current_action": {
            "id": "df25724f-e308-4c89-9325-cf56cd09249e",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": "answer"
        },
        "forward_action_id": "00000000-0000-0000-0000-000000000000",
        "actions": [
            {
                "id": "df25724f-e308-4c89-9325-cf56cd09249e",
                "next_id": "00000000-0000-0000-0000-000000000000",
                "type": "answer"
            },
            {
                "id": "2e7ec294-fc66-4039-8446-6590b82ed54f",
                "next_id": "00000000-0000-0000-0000-000000000000",
                "type": "talk",
                "option": {
                    "text": "hello. welcome to voipbin. This is test message. Please enjoy the voipbin's service. thank you.",
                    "gender": "female",
                    "language": "en-US"
                }
            }
        ],
        "tm_create": "2022-04-11 00:23:54.724620",
        "tm_update": "2022-04-11 00:23:54.840938",
        "tm_delete": "9999-01-01 00:00:00.000000"
    }
}

activeflow_deleted

The notification message for the activeflow delete.

{
    "type": "activeflow_deleted",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of activeflow. See detail here.

Example

{
    "type": "activeflow_deleted",
    "data": {
        "id": "74ac5405-7c70-4184-9388-1c9f8f8ce25f",
        "flow_id": "d157ce07-0360-4cad-9007-c8ab89fccf9c",
        "customer_id": "00000000-0000-0000-0000-000000000000",
        "reference_type": "call",
        "reference_id": "5371e9db-d035-4db6-a8d6-0994d33e744e",
        "current_action": {
            "id": "2e7ec294-fc66-4039-8446-6590b82ed54f",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": "talk",
            "option": {
                "text": "hello. welcome to voipbin. This is test message. Please enjoy the voipbin's service. thank you.",
                "gender": "female",
                "language": "en-US"
            }
        },
        "forward_action_id": "00000000-0000-0000-0000-000000000000",
        "actions": [
            {
                "id": "df25724f-e308-4c89-9325-cf56cd09249e",
                "next_id": "00000000-0000-0000-0000-000000000000",
                "type": "answer"
            },
            {
                "id": "2e7ec294-fc66-4039-8446-6590b82ed54f",
                "next_id": "00000000-0000-0000-0000-000000000000",
                "type": "talk",
                "option": {
                    "text": "hello. welcome to voipbin. This is test message. Please enjoy the voipbin's service. thank you.",
                    "gender": "female",
                    "language": "en-US"
                }
            }
        ],
        "tm_create": "2022-04-11 00:23:54.724620",
        "tm_update": "2022-04-11 00:23:55.134500",
        "tm_delete": "9999-01-01 00:00:00.000000"
    }
}

call_created

The notification message for the call create.

{
    "type": "call_created",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of call. See detail here.

Example

{
    "type": "call_created",
    "data": {
        "id": "5371e9db-d035-4db6-a8d6-0994d33e744e",
        "flow_id": "d157ce07-0360-4cad-9007-c8ab89fccf9c",
        "type": "flow",
        "master_call_id": "00000000-0000-0000-0000-000000000000",
        "chained_call_ids": [],
        "recording_id": "00000000-0000-0000-0000-000000000000",
        "recording_ids": [],
        "source": {
            "type": "tel",
            "target": "+821100000002",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        "destination": {
            "type": "tel",
            "target": "+821100000001",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        "status": "ringing",
        "action": {
            "id": "00000000-0000-0000-0000-000000000001",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": ""
        },
        "direction": "incoming",
        "hangup_by": "",
        "hangup_reason": "",
        "tm_create": "2022-04-11 00:23:53.636000",
        "tm_update": "9999-01-01 00:00:00.000000",
        "tm_progressing": "9999-01-01 00:00:00.000000",
        "tm_ringing": "9999-01-01 00:00:00.000000",
        "tm_hangup": "9999-01-01 00:00:00.000000"
    }
}

call_ringing

The notification message for the call ringing.

{
    "type": "call_ringing",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of call. See detail here.

Example

{
    "type": "call_ringing",
    "data": {
        "id": "ad132775-1ab2-485e-856f-72c2e383cdc6",
        "flow_id": "6da52ef9-7d7d-48e4-8bca-921e7b78e47c",
        "type": "flow",
        "master_call_id": "1fe1356f-3f7f-4ff9-9d33-08136b38f506",
        "chained_call_ids": [],
        "recording_id": "00000000-0000-0000-0000-000000000000",
        "recording_ids": [],
        "source": {
            "type": "tel",
            "target": "+15559876543",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        "destination": {
            "type": "tel",
            "target": "+15559876543",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        "status": "ringing",
        "action": {
            "id": "00000000-0000-0000-0000-000000000001",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": ""
        },
        "direction": "outgoing",
        "hangup_by": "",
        "hangup_reason": "",
        "tm_create": "2022-03-29 15:08:01.815004",
        "tm_update": "2022-03-29 15:08:03.421646",
        "tm_progressing": "9999-01-01 00:00:00.000000",
        "tm_ringing": "2022-03-29 15:08:03.314000",
        "tm_hangup": "9999-01-01 00:00:00.000000"
    }
}

call_answered

The notification message for the call answer.

{
    "type": "call_answered",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of call. See detail here.

Example

{
    "type": "call_answered",
    "data": {
        "id": "5371e9db-d035-4db6-a8d6-0994d33e744e",
        "flow_id": "d157ce07-0360-4cad-9007-c8ab89fccf9c",
        "type": "flow",
        "master_call_id": "00000000-0000-0000-0000-000000000000",
        "chained_call_ids": [],
        "recording_id": "00000000-0000-0000-0000-000000000000",
        "recording_ids": [],
        "source": {
            "type": "tel",
            "target": "+821100000002",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        "destination": {
            "type": "tel",
            "target": "+821100000001",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        "status": "progressing",
        "action": {
            "id": "df25724f-e308-4c89-9325-cf56cd09249e",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": "answer",
            "tm_execute": "2022-04-11 00:23:55.012416032"
        },
        "direction": "incoming",
        "hangup_by": "",
        "hangup_reason": "",
        "tm_create": "2022-04-11 00:23:53.636000",
        "tm_update": "2022-04-11 00:23:55.130190",
        "tm_progressing": "2022-04-11 00:23:55.026000",
        "tm_ringing": "9999-01-01 00:00:00.000000",
        "tm_hangup": "9999-01-01 00:00:00.000000"
    }
}

call_updated

The notification message for the call update.

{
    "type": "call_updated",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of call. See detail here.

Example

{
    "type": "call_updated",
    "data": {
        "id": "bf682a17-6b3f-412c-bbac-faa81fb9ada3",
        "flow_id": "70875796-0497-4ff9-acd0-e226a14495a9",
        "type": "flow",
        "master_call_id": "00000000-0000-0000-0000-000000000000",
        "chained_call_ids": [
            "a876f057-bb20-4b87-824c-d7afa3e71af5"
        ],
        "recording_id": "00000000-0000-0000-0000-000000000000",
        "recording_ids": [],
        "source": {
            "type": "tel",
            "target": "test11",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        "destination": {
            "type": "tel",
            "target": "+821100000004",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        "status": "hangup",
        "action": {
            "id": "4aae4342-d702-4e23-9c14-64dc20d2075d",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": "confbridge_join",
            "option": {
                "confbridge_id": "821fc304-0ed8-4e93-8a0a-c23312c062be"
            },
            "tm_execute": "2022-03-29 14:10:06.409155828"
        },
        "direction": "incoming",
        "hangup_by": "remote",
        "hangup_reason": "normal",
        "tm_create": "2022-03-29 14:09:52.886000",
        "tm_update": "2022-03-29 14:10:33.709605",
        "tm_progressing": "2022-03-29 14:09:54.629000",
        "tm_ringing": "9999-01-01 00:00:00.000000",
        "tm_hangup": "2022-03-29 14:10:33.105000"
    }
}

call_hungup

The notification message for the call hangup.

{
    "type": "call_hungup",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of call. See detail here.

Example

{
    "type": "call_hungup",
    "data": {
        "id": "593555d2-787e-4b06-862f-407bb2e43be1",
        "flow_id": "d157ce07-0360-4cad-9007-c8ab89fccf9c",
        "type": "flow",
        "master_call_id": "00000000-0000-0000-0000-000000000000",
        "chained_call_ids": [],
        "recording_id": "00000000-0000-0000-0000-000000000000",
        "recording_ids": [],
        "source": {
            "type": "tel",
            "target": "+821100000002",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        "destination": {
            "type": "tel",
            "target": "+821100000001",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        "status": "hangup",
        "action": {
            "id": "2e7ec294-fc66-4039-8446-6590b82ed54f",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": "talk",
            "option": {
                "text": "hello. welcome to voipbin. This is test message. Please enjoy the voipbin's service. thank you.",
                "gender": "female",
                "language": "en-US"
            },
            "tm_execute": "2022-04-11 06:10:55.918010931"
        },
        "direction": "incoming",
        "hangup_by": "remote",
        "hangup_reason": "normal",
        "tm_create": "2022-04-11 06:10:54.788000",
        "tm_update": "2022-04-11 06:10:58.431000",
        "tm_progressing": "2022-04-11 06:10:55.765000",
        "tm_ringing": "9999-01-01 00:00:00.000000",
        "tm_hangup": "2022-04-11 06:10:58.431000"
    }
}

queue_created

Notification message for queue create.

{
    "type": "queue_created",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of queue. See detail here.

queue_updated

The notification message for the queue update.

{
    "type": "queue_updated",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of queue. See detail here.

queue_deleted

The notification message for the queue delete.

{
    "type": "queue_deleted",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of queue. See detail here.

queuecall_created

The notification message for the queuecall create.

{
    "type": "queuecall_created",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of queuecall. See detail here.

Example

{
    "type": "queuecall_created",
    "data": {
        "id": "c7c1e226-8c86-4b43-9606-2d5bb2059a09",
        "reference_type": "call",
        "reference_id": "1fe1356f-3f7f-4ff9-9d33-08136b38f506",
        "status": "wait",
        "service_agent_id": "00000000-0000-0000-0000-000000000000",
        "tm_create": "2022-03-29 15:07:46.111715",
        "tm_service": "9999-01-01 00:00:00.000000",
        "tm_update": "9999-01-01 00:00:00.000000",
        "tm_delete": "9999-01-01 00:00:00.000000"
    }
}

queuecall_entering

Notification message for queuecall is entering to the agent’s conference room.

{
    "type": "queuecall_entering",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of queuecall. See detail here.

Example

{
    "type": "queuecall_entering",
    "data": {
        "id": "c7c1e226-8c86-4b43-9606-2d5bb2059a09",
        "reference_type": "call",
        "reference_id": "1fe1356f-3f7f-4ff9-9d33-08136b38f506",
        "status": "entering",
        "service_agent_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
        "tm_create": "2022-03-29 15:07:46.111715",
        "tm_service": "2022-03-29 15:08:02.233858",
        "tm_update": "2022-03-29 15:08:02.233858",
        "tm_delete": "9999-01-01 00:00:00.000000"
    }
}

queuecall_kicking

The notification message for the queuecall is being kicked.

{
    "type": "queuecall_kicking",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of queuecall. See detail here.

Example

{
    "type": "queuecall_kicking",
    "data": {
        "id": "c7c1e226-8c86-4b43-9606-2d5bb2059a09",
        "reference_type": "call",
        "reference_id": "1fe1356f-3f7f-4ff9-9d33-08136b38f506",
        "status": "entering",
        "service_agent_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
        "tm_create": "2022-03-29 15:07:46.111715",
        "tm_service": "2022-03-29 15:08:02.233858",
        "tm_update": "2022-03-29 15:08:02.233858",
        "tm_delete": "9999-01-01 00:00:00.000000"
    }
}

queuecall_serviced

The notification message for the queuecall is serviced.

{
    "type": "queuecall_serviced",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of queuecall. See detail here.

Example

{
    "type": "queuecall_serviced",
    "data": {
        "id": "c7c1e226-8c86-4b43-9606-2d5bb2059a09",
        "reference_type": "call",
        "reference_id": "1fe1356f-3f7f-4ff9-9d33-08136b38f506",
        "status": "service",
        "service_agent_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
        "tm_create": "2022-03-29 15:07:46.111715",
        "tm_service": "2022-03-29 15:08:04.811442",
        "tm_update": "2022-03-29 15:08:04.811442",
        "tm_delete": "9999-01-01 00:00:00.000000"
    }
}

queuecall_done

The notification message for the queuecall is done.

{
    "type": "queuecall_done",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of queuecall. See detail here.

Example

{
    "type": "queuecall_done",
    "data": {
        "id": "c7c1e226-8c86-4b43-9606-2d5bb2059a09",
        "reference_type": "call",
        "reference_id": "1fe1356f-3f7f-4ff9-9d33-08136b38f506",
        "status": "done",
        "service_agent_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
        "tm_create": "2022-03-29 15:07:46.111715",
        "tm_service": "2022-03-29 15:08:04.811442",
        "tm_update": "2022-03-29 15:08:25.814885",
        "tm_delete": "2022-03-29 15:08:25.814885"
    }
}

queuecall_abandoned

The notification message for the queuecall is abandoned.

{
    "type": "queuecall_abandoned",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of queuecall. See detail here.

agent_created

The notification message for the agent create.

{
    "type": "agent_created",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of agent. See detail here.

agent_updated

Notification message for agent update.

The notification message for the agent update.

{
    "type": "agent_updated",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of agent. See detail here.

agent_deleted

The notification message for the agent delete.

{
    "type": "agent_deleted",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of agent. See detail here.

agent_status_updated

The notification message for the agent’s status update.

{
    "type": "agent_status_updated",
    "data": {
        ...
    }
}

type: The webhook type.
data: The detail of agent. See detail here.

Example

{
    "type": "agent_status_updated",
    "data": {
        "id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
        "username": "test1",
        "name": "test agent 1",
        "detail": "test agent. username test1",
        "ring_method": "ringall",
        "status": "available",
        "permission": 0,
        "tag_ids": [
            "d7450dda-21e0-4611-b09a-8d771c50a5e6"
        ],
        "addresses": [
            {
                "type": "tel",
                "target": "+15559876543",
                "target_name": "",
                "name": "",
                "detail": ""
            }
        ],
        "tm_create": "2021-11-29 06:09:07.263846",
        "tm_update": "2022-03-29 15:08:00.814900",
        "tm_delete": "9999-01-01 00:00:00.000000"
    }
}

Tutorial

Create a Webhook

Register a webhook endpoint to receive real-time event notifications from VoIPBIN. Webhooks notify your server when events occur (call status changes, messages received, etc.).

$ curl --location --request POST 'https://api.voipbin.net/v1.0/webhooks?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "name": "Production Webhook",
        "detail": "Main webhook for production events",
        "uri": "https://your-server.com/voipbin/webhook",
        "method": "POST",
        "event_types": [
            "call.status",
            "message.received",
            "recording.completed"
        ]
    }'

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "12345678-1234-1234-1234-123456789012",
    "name": "Production Webhook",
    "detail": "Main webhook for production events",
    "uri": "https://your-server.com/voipbin/webhook",
    "method": "POST",
    "event_types": [
        "call.status",
        "message.received",
        "recording.completed"
    ],
    "status": "active",
    "tm_create": "2026-01-20 10:30:00.000000",
    "tm_update": "2026-01-20 10:30:00.000000",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

The webhook is now active and will receive POST requests when specified events occur.

Get List of Webhooks

Retrieve all registered webhooks for your account.

$ curl --location --request GET 'https://api.voipbin.net/v1.0/webhooks?token=<YOUR_AUTH_TOKEN>'

{
    "result": [
        {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "customer_id": "12345678-1234-1234-1234-123456789012",
            "name": "Production Webhook",
            "detail": "Main webhook for production events",
            "uri": "https://your-server.com/voipbin/webhook",
            "method": "POST",
            "event_types": [
                "call.status",
                "message.received"
            ],
            "status": "active",
            "tm_create": "2026-01-20 10:30:00.000000",
            "tm_update": "2026-01-20 10:30:00.000000",
            "tm_delete": "9999-01-01 00:00:00.000000"
        }
    ]
}

Update a Webhook

Modify an existing webhook’s configuration, such as changing the URI or event types.

$ curl --location --request PUT 'https://api.voipbin.net/v1.0/webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "name": "Production Webhook - Updated",
        "event_types": [
            "call.status",
            "call.completed",
            "message.received",
            "recording.completed",
            "transcribe.completed"
        ]
    }'

Delete a Webhook

Remove a webhook when it’s no longer needed.

$ curl --location --request DELETE 'https://api.voipbin.net/v1.0/webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890?token=<YOUR_AUTH_TOKEN>'

Webhook Event Types

VoIPBIN sends different event types to your webhook endpoint. For the complete list, see Webhook Structure.

Call Events:

call_created - Call initiated
call_ringing - Call is ringing
call_answered - Call was answered
call_updated - Call status changed
call_hungup - Call ended

Message Events:

message_created - Message created
message_updated - Message status changed
message_deleted - Message deleted

Recording Events:

recording_created - Recording started
recording_updated - Recording status changed
recording_deleted - Recording deleted

Transcription Events:

transcribe_created - Transcription started
transcribe_updated - Transcription progress update
transcribe_deleted - Transcription deleted
transcript_created - Transcript segment created

Queue Events:

queue_created - Queue created
queue_updated - Queue updated
queuecall_created - Call joined queue
queuecall_kicking - Agent assigned to queue call
queuecall_serviced - Queue call being handled

Conference Events:

conference_created - Conference created
conference_updated - Conference updated
confbridge_created - Conference bridge created
confbridge_updated - Participant joined/left

Activeflow Events:

activeflow_created - Flow execution started
activeflow_updated - Flow execution progressed
activeflow_deleted - Flow execution ended

Receiving Webhook Events

Your webhook endpoint should accept POST requests and process the JSON payload. Here’s an example webhook server implementation:

Python (Flask) Example:

from flask import Flask, request, jsonify
import hmac
import hashlib

app = Flask(__name__)

@app.route('/voipbin/webhook', methods=['POST'])
def voipbin_webhook():
    # Get the webhook payload
    payload = request.get_json()

    # Process different event types
    event_type = payload.get('type')

    if event_type == 'call_hungup':
        call_id = payload['data']['id']
        status = payload['data']['hangup_reason']

        print(f"Call {call_id} ended: {status}")

        # Your business logic here
        # - Update CRM
        # - Send notifications
        # - Trigger workflows

    elif event_type == 'message_created':
        message_id = payload['data']['id']
        from_number = payload['data']['source']['target']
        text = payload['data']['text']

        print(f"Message from {from_number}: {text}")

        # Process the message
        # - Auto-reply
        # - Route to agent
        # - Store in database

    elif event_type == 'recording_updated':
        recording_id = payload['data']['id']
        status = payload['data']['status']

        print(f"Recording {recording_id} status: {status}")

        # Handle recording
        # - Download and store
        # - Transcribe
        # - Send to customer

    # Return 200 OK to acknowledge receipt
    return jsonify({'status': 'received'}), 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Node.js (Express) Example:

const express = require('express');
const app = express();

app.use(express.json());

app.post('/voipbin/webhook', (req, res) => {
    const payload = req.body;
    const eventType = payload.type;

    console.log(`Received event: ${eventType}`);

    switch(eventType) {
        case 'call_hungup':
            handleCallHungup(payload.data);
            break;
        case 'message_created':
            handleMessageCreated(payload.data);
            break;
        case 'recording_updated':
            handleRecordingUpdated(payload.data);
            break;
        default:
            console.log(`Unknown event type: ${eventType}`);
    }

    // Acknowledge receipt
    res.status(200).json({ status: 'received' });
});

function handleCallHungup(data) {
    console.log(`Call ${data.id} ended`);
    // Your logic here
}

function handleMessageCreated(data) {
    console.log(`Message from ${data.source.target}: ${data.text}`);
    // Your logic here
}

function handleRecordingUpdated(data) {
    console.log(`Recording ${data.id} status: ${data.status}`);
    // Your logic here
}

app.listen(5000, () => {
    console.log('Webhook server listening on port 5000');
});

Testing Webhooks

Local Development:

Use tools like ngrok to expose your local server for testing:

# Install ngrok
$ brew install ngrok  # macOS
$ snap install ngrok  # Linux

# Start your webhook server locally
$ python webhook_server.py

# Expose it via ngrok
$ ngrok http 5000

# Use the ngrok URL in your webhook configuration
# Example: https://abc123.ngrok.io/voipbin/webhook

Testing with curl:

Simulate a webhook event to test your endpoint:

$ curl --location --request POST 'http://localhost:5000/voipbin/webhook' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "type": "call_hungup",
        "data": {
            "id": "test-call-id",
            "hangup_reason": "normal",
            "source": {
                "type": "tel",
                "target": "+15551234567"
            },
            "destination": {
                "type": "tel",
                "target": "+15559876543"
            }
        }
    }'

Webhook Payload Structure

All webhook events follow this structure:

{
    "type": "call_hungup",
    "data": {
        // Event-specific data
        // Structure varies by event type
    }
}

Fields:

type: Type of event that occurred (e.g., call_hungup, message_created)
data: Event-specific data (varies by event type). See Webhook Structure for details.

Best Practices

1. Acknowledge Quickly: - Return 200 OK immediately upon receiving the webhook - Process time-consuming tasks asynchronously (queue jobs, background workers) - VoIPBIN expects a response within 5 seconds

2. Handle Duplicates: - Webhooks may be delivered more than once - Use the event ID or timestamp to detect and ignore duplicates - Implement idempotent processing

3. Secure Your Endpoint: - Use HTTPS for production webhooks - Validate webhook authenticity (check source IP, use signatures) - Implement rate limiting to prevent abuse

4. Error Handling: - Log all webhook events for debugging - Return appropriate HTTP status codes - Implement retry logic for failed processing

5. Event Filtering: - Subscribe only to events you need - Filter events in your webhook handler - Update webhook configuration as requirements change

6. Monitoring: - Track webhook delivery success/failure rates - Set up alerts for high failure rates - Monitor webhook processing times

Common Use Cases

CRM Integration: Automatically update your CRM when calls end:

if event_type == 'call_hungup':
    call_data = payload['data']

    # Update CRM contact record
    crm.update_contact(
        phone=call_data['destination']['target'],
        last_call_date=call_data['tm_hangup'],
        hangup_reason=call_data['hangup_reason']
    )

Auto-Reply to Messages: Respond automatically to incoming messages:

if event_type == 'message_created':
    message = payload['data']
    from_number = message['source']['target']

    # Send auto-reply
    voipbin_api.send_message(
        to=from_number,
        text="Thanks for your message! We'll respond soon."
    )

Recording Distribution: Email recordings to stakeholders when ready:

if event_type == 'recording_updated':
    recording = payload['data']

    if recording['status'] == 'done':
        # Send email with recording info
        email.send(
            to='[email protected]',
            subject='Call Recording Available',
            body=f'Recording ID: {recording["id"]}'
        )

For more information about webhook configuration and event types, see Webhook Overview.