> ## Documentation Index > Fetch the complete documentation index at: https://docs.superoffice.com/llms.txt > Use this file to discover all available pages before exploring further. # SuperOffice Webhooks > Introduction to SuperOffice webhooks for developers - webhook definitions, subscriptions, notifications, and CRMScript handlers. No longer must integrations poll SuperOffice and ask for the latest changes. SuperOffice Webhooks actively send messages to subscribers when events occur in SuperOffice and provide an opportunity for applications to react accordingly. This feature requires a license for [Development Tools][1] or the CRM Suite **Core** plan. [1]: /en/admin/license/expander-services Webhooks are a means to broadcast events that happen inside SuperOffice as they occur. A webhook payload includes information that describes what has changed and is broadcast to all applications that have subscribed to a corresponding event. The webhook workflow begins with applications subscribing to interesting events. The way an application does this is by adding one or more webhook definitions in SuperOffice. For example, the Partner Application registers an interest in `contact.created` events with SuperOffice. From then on, whenever a contact record is created, SuperOffice will notify the Partner Application that the event has occurred. The Partner Application can then update its own state, get more information, or just log the information. Let's start by looking at a webhook definition - what the Partner Application uses to register its interest in events with SuperOffice. ![x][img1] ## Webhook definition A webhook subscription contains the following properties: | Property name | Description | | ------------- | ------------------------------------------------------------------------------------------ | | Name | A name to distinguish events from one another. | | Events | An array of `entity.event` names. | | TargetURL | Defines a URL where webhook payloads are sent. Must be HTTPS and must respond to POST | | Secret | Optional shared secret. Used for creating a SHA256 HMAC if set. | | State | Unknown = 0, Active = 1, Stopped = 2, TooManyErrors = 3 | | Type | Name of webhook plugin that handles dispatching this webhook: "webhook", "CRMScript", etc. | | Headers | Hook-specific custom headers to be added to the webhook payload. | | Properties | Hook-specific data properties to be added to the webhook payload. | | ErrorEmail | Email address to send email notification when webhook disabled. | While a webhook `name` need not be unique, it should be unique enough to distinguish it from others and describe its purpose. The `Events` property is an array of one or more event names the subscriber is subscribing to. The format of a single event name is `.`, where *entity* is one of the [available entities][1], and the event is one of *created*, *changed* or *deleted*. `TargetURL` defines where to send the POST request containing the webhook payload. The webhook payload contains all relevant information needed by subscribers to take action. The Target URL must be HTTPS, and it must respond to a POST request with a 200 OK response. The HTTPS certificate must be valid. If the certificate is not valid (i.e. self-signed, expired, not valid for host-name, revoked, etc), then the webhook will be rejected. When security is important, which should be always, a webhook definition specifies a shared secret that both the sender and receiver use to validate a webhook payload. When an event notification is sent, the webhook payload is hashed and base64 encoded and the resulting value is added to a header in the POST request. The header key is `X-SuperOffice-Signature`. It's up to the subscriber to [validate the header value][4]. The `state` of a webhook is by default **Active** but can be set to **Stopped**. If the target URL does not return a successful 200 response after 9 consecutive delivery failures across 3 retry cycles of 3 attempts each, SuperOffice sets the state of the webhook to **TooManyErrors**. A webhook `Type` must match the plugin responsible for dispatching notifications. As of this writing, the only supported value is "webhook". Webhook `Headers` are any additional header values SuperOffice appends to a request sent with each notification. Headers are a simple "string":"string" value. Webhook `Properties` are any additional values SuperOffice should append to each request sent with each notification. Properties are a "string": \{object} value. Webhook `ErrorEmail` is one email address used to send error notifications to when a webhook fails too many times and the state is set to TooManyErrors due to an unreachable URL or permanent failure. ## CRMScript hooks Webhooks can also target CRMScripts by using the `Type: "crmscript"`. ## Learn more about the SuperOffice Webhooks API Applies to Web client and NetServer Services only. Events are only raise by changes in the root entity table, such as contact, person, sale Events are **not emitted** for row changes in foreign key tables, such as phone, email, udcontactsmall. udprojectlarge. * [Event details][1] * [Webhook subscription][2] * [Webhook notification][3] * [Webhook secrets][4] [1]: ./event-details [2]: ./subscription [3]: ./notification [4]: ./security [img1]: /media/loc/en/automation/webhook-subscribe-notification.png ## Related topics - [Webhooks](/en/automation/webhook/index.md) - [Webhooks panel](/en/automation/webhook/admin/index.md) - [SuperOffice.WebApi.Data.Webhook TestWebhookRequest](/en/api/reference/webapi/SuperOffice.WebApi.Data.Webhook_TestWebhookRequest.md) - [SuperOffice.WebApi.Data.Webhook GetAllWebhooksRequest](/en/api/reference/webapi/SuperOffice.WebApi.Data.Webhook_GetAllWebhooksRequest.md) - [SuperOffice.WebApi.Data.Webhook](/en/api/reference/webapi/SuperOffice.WebApi.Data.Webhook.md) - [SuperOffice.WebApi.Agents.WebhookAgent](/en/api/reference/webapi/SuperOffice.WebApi.Agents.WebhookAgent.md)