Webhooks

The Webhooks plugin sends automated HTTP requests based on events, and listens for HTTP requests to trigger specific events. Use it to notify external systems when something happens in Blesta (outgoing webhooks), or to let external systems trigger events in Blesta (incoming webhooks).

Tie-Ins*

Widgets	Nav Links	Client Cards	Automation Tasks	Email Templates	ACL Permissions	Search	Events	Service Management
NONE	YES	NONE	YES	NONE	YES	NONE	YES	NONE

* Plugins are powerful and are not limited to the tie-ins listed above, these are just some of the most common

Installing Webhooks

To install the Webhooks plugin, visit [Settings] > [Company] > [Plugins] > Available, and click the "Install" button for Webhooks.

A message will be displayed, indicating that the plugin was successfully installed.

Once installed, webhooks are managed under [Tools] > [Webhooks].

Managing Webhooks

The Webhooks page lists your webhooks under two tabs:

• Outgoing — "Sends an HTTP request to a URL when an event is triggered. The request can be sent using GET, POST, PUT or JSON."
• Incoming — "Receives an HTTP request and triggers an event on the system using the parameters received in the request. The request can be received using GET, POST or JSON."

Each webhook in the list shows its Callback, Event, and Method, with options to view its Logs, Edit, or Delete it.

Adding a Webhook

Click "Add Webhook" on the Webhooks page.

Field Name	Description
Callback	Where the request is sent or received. For outgoing webhooks, enter the full URL the request should be sent to. For incoming webhooks, enter a name — the webhook can then be triggered at https://yourdomain.com/plugin/webhooks/trigger/index/[Callback Name].
Event	Check one or more events the webhook responds to (outgoing) or triggers (incoming). Events cover most system actions, e.g. Clients.add, Invoices.setClosed, Services.suspend.
Callback (type)	Select "Outgoing" or "Incoming".
Method	Select "GET", "POST", "PUT", "POST JSON", or "PUT JSON".
Fields Map	Optionally rename event fields to custom names before they are sent to the callback. Subfields are separated by a period (e.g. vars.status). Click "Add Field" and enter the Original Field and New Field for each mapping.

When finished, click "Add Webhook".

Outgoing request headers

Outgoing webhook requests include the headers X-Blesta-Event (the event name) and X-Webhook-Id, and are sent with the user agent Blesta-Webhook. Use these to identify and route requests on the receiving end.

Incoming webhooks are unauthenticated

An incoming webhook is triggered by anyone who requests its URL — the callback name is the only secret. Use a long, unguessable callback name, and treat the URL like a credential.

Webhook Logs

Every webhook execution is logged. Click "Logs" next to a webhook to see its history, or "View All Logs" for all webhooks. Each log entry records the Webhook, Event, Response, Method, HTTP Response, Date Triggered, and Last Retry. Logs may be filtered by Webhook, Event, HTTP Status, and date range.

A failed delivery can be re-attempted with the "Resend" option on the log entry.

Automation Tasks

Webhooks registers two Automation Tasks under [Settings] > [Company] > [Automation]:

Task	Description
Clear Cache	Clears the event observers list cache. Runs daily.
Clean up Webhook Logs	Deletes webhook logs older than the configured log retention period (the Rotation Policy under [Settings] > [Company] > [Logging]). Runs daily.

Permissions

The plugin registers a "Webhooks" ACL permission under the Tools group, so access to webhook management can be restricted per staff group under [Settings] > [System] > [Staff] > [Staff Groups].