# Webhook Events

PortSIP PBX provides a **Webhook API** that allows external systems to receive **near real-time notifications** when events occur within the PBX. Webhooks offer an efficient alternative to polling the REST API and are designed to support **event-driven integrations**.

By using webhooks, you can trigger actions immediately when specific events occur (for example, events being assigned, deferred, or canceled). This enables use cases such as:

* Live dashboards and wallboards
* Gamification and performance tracking
* Real-time data synchronization with external systems
* Workflow automation and event-driven business logic

The webhook mechanism is based on **HTTP POST requests**. When an event occurs, PortSIP PBX sends an HTTP request containing the **event payload** to a configured **consumer endpoint URL**.

***

### Development Guidelines

When consuming the PortSIP PBX Webhook API, we strongly recommend following these best practices to ensure compatibility and long-term stability:

* All webhook payloads are standard **JSON objects**, encoded using **UTF-8**.
* Always access fields by **field name**, not by position or order within the JSON document.
* Do **not** rely on the ordering of elements in a JSON object unless explicitly documented.
* Always use a **JSON parser** to process webhook payloads. Avoid parsing JSON using regular expressions.
* Design your implementation to **gracefully handle new fields** that may be added to event payloads without prior notice.
* Existing fields will be preserved whenever possible to maintain **backward compatibility**.

***

### Getting Started

The following sections will help you configure and start using PortSIP PBX Webhooks:

* [Create a Webhook](/development-portsip/webhook-notifications/registering-a-webhook.md) – Configure webhook endpoints in PortSIP PBX
* [Receiving Webhooks](/development-portsip/webhook-notifications/receiving-events-via-a-webhook.md) – Handle incoming HTTP event notifications
* [Event Reference](/development-portsip/webhook-notifications/event-reference.md) – Review supported event types and payload structures


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://support.portsip.com/development-portsip/webhook-notifications.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.