> For the complete documentation index, see [llms.txt](https://docs.enate.net/enate-help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enate.net/enate-help/enate-apis-and-webhooks/webhooks.md).

# Webhooks

## **What is a Webhook?** <a href="#what-is-a-webhook" id="what-is-a-webhook"></a>

A **webhook** (also called a web call back or HTTP push API) is a way for an application to provide other applications with real-time information. You can use Webhooks for more seamless integration with your other systems.

You can subscribe to webhooks so your systems are notified of events in Enate as they happen, allowing you to get data immediately. This makes webhooks much more efficient for both provider and consumer. An example might be if a new Case gets created, if this happens then Enate will send a request to your system to let you know.

Enate's Webhooks are outbound only. Enate sends an HTTP POST to a URL you provide whenever an event you've subscribed to occurs. There's no Webhook mechanism for sending events into Enate, that's what the Enate APIs are for.

It's important to be familiar with Webhooks before embarking on using them. You can check out a list of the Webhooks currently available in Enate:

{% content-ref url="/pages/MV50WMirrvpGOIkNQPMi" %}
[List of Enate's Webhooks](https://docs.enate.net/enate-help/enate-apis-and-webhooks/webhooks/list-of-enates-webhooks.md)
{% endcontent-ref %}

APIs exist in Enate to allow you to subscribe to a Webhook, to see your existing subscriptions, to update them and to unsubscribe. Check out the details for this in the API Webhook Subscription section:

{% content-ref url="/pages/-MWn\_erOfl2edMEqVmdl" %}
[API Webhook Subscription](https://docs.enate.net/enate-help/enate-apis-and-webhooks/webhooks/api-webhook-subscription.md)
{% endcontent-ref %}

Before you build your receiving endpoint, read the delivery and failure handling page. How Enate retries, when it stops trying, and why you may see the same event twice are the things you need to design around:

{% content-ref url="/pages/UiOBvIt7SIgRG3YsxevK" %}
[Webhook Delivery and Failure Handling](https://docs.enate.net/enate-help/enate-apis-and-webhooks/webhooks/webhook-delivery-and-failure-handling.md)
{% endcontent-ref %}

Make sure to check out our sample Webhook integrations section here:

{% content-ref url="/pages/-MjTRoLnpYYnjjk8tdeg" %}
[Auto-notify other apps of new Cases, Tickets & comms with Enate's Webhooks](https://docs.enate.net/enate-help/integrations/enate-integrations/webhook-sample-auto-notifying-other-apps-of-new-cases-tickets-and-comms.md)
{% endcontent-ref %}

This section contains common webhook troubleshooting questions to help with any general queries you might have:

{% content-ref url="/pages/-MXbmoHKvc5YD00pXdoi" %}
[Webhook Troubleshooting](https://docs.enate.net/enate-help/enate-apis-and-webhooks/webhooks/webhook-troubleshooting.md)
{% endcontent-ref %}

{% hint style="info" %}
Note: the term 'Packet' is used in places throughout this documentation to refer to Enate's Work Items, which can be of type Case, Ticket or Action.
{% endhint %}

## Webhook Authentication

Authentication for creating or updating a Webhook subscription is the same as for any other Enate API. The account creating the subscription must have a Builder role, as well as permission to access data related to the requested entity (Customer, Contract etc.). There are two main places where Webhook authentication takes place:

### **1. On the Webhook Provider side (i.e. Enate):**

When the Webhook subscription is created the subscriber needs to provide valid user credentials (as with any other API call) and where the subscription refers to a specific entity (i.e. events related to a Company) the account needs to have permissions on that entity.

{% hint style="info" %}
Note: This check is also carried out when every Webhook message is being prepared, in case the account's permissions have changed since the subscription was originally created. If the account no longer has permission, that individual message isn't sent. The subscription itself stays in place, so messages resume if the permission is restored.
{% endhint %}

Permission is checked against different objects depending on what you subscribed to:

| Subscription is scoped to                                         | What the permission check looks at                          |
| ----------------------------------------------------------------- | ----------------------------------------------------------- |
| Company, Contract, Service, Case definition, Ticket definition    | Read permission on that object                              |
| A specific work item (Packet)                                     | Read permission on the work item's permission source object |
| An Action definition                                              | Read permission on the parent Case definition               |
| Schedule                                                          | No check, Schedules don't carry permissions                 |
| BusinessObjectCreated and BusinessObjectTypeUpdated subscriptions | No check, these aren't scoped to an individual object       |

### **2. On the Webhooks Subscriber side (i.e. your systems):**

Every Webhook subscription has a signature, a GUID generated by Enate when the subscription is created. Enate sends it in the `x-enate-signature` header of every message for that subscription, so you can confirm the message came from Enate.

The signature is fixed for the life of the subscription. Updating a subscription doesn't change it. If you need a new signature, unsubscribe and create the subscription again.

### **Optional - HTTP Header**

In addition to the above authentication points, Webhook subscriptions have an optional custom HTTP header which can contain any key/value data the subscriber requires i.e. it could be used to include a further key generated by the subscriber which they can use to authenticate received messages.

{% hint style="info" %}
Note: a header name can only use letters, digits and the characters ! # $ % & ' \* + - . ^ \_ \` | \~, so it can't contain a space. A `CustomHeader` of "New packet subscription" is rejected with message 990813: write it as `New-packet-subscription`. Enate sends the header name exactly as you saved it.
{% endhint %}

### Securing Your Receiving Endpoint

A few practical points for the endpoint you point `SubscriberURL` at:

* Use an HTTPS URL. Enate accepts `http` and `https`, but the signature and any custom header travel in clear text over plain HTTP.
* Compare the `x-enate-signature` value against the signature Enate returned when you created the subscription, and reject anything that doesn't match.
* Treat the signature as a shared secret. Anyone who has it can imitate Enate messages for that subscription.
* Reply quickly with a 2xx status code and do your processing afterwards. Enate treats every non-2xx response as a failure and retries, and that includes a 4xx, so you can't decline a message by returning a client error code.

### Sample Integration Patterns Using Enate's Webhooks

{% content-ref url="/pages/-MjTRoLnpYYnjjk8tdeg" %}
[Auto-notify other apps of new Cases, Tickets & comms with Enate's Webhooks](https://docs.enate.net/enate-help/integrations/enate-integrations/webhook-sample-auto-notifying-other-apps-of-new-cases-tickets-and-comms.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.enate.net/enate-help/enate-apis-and-webhooks/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
