Send webhooks to a third-party service when assets are created, edited, or deleted
A webhook is an HTTP callback that is generated by a specific event. In other words, a webhook lets Orange Logic send information to an external application in real time. Orange Logic webhooks are an efficient, automated solution to managing thousands of assets. You can create webhooks that trigger the Orange Logic platform to send information to an external website when Orange Logic assets are created, edited, deleted, and more. This “set it and forget it” approach helps you keep your assets consistent and up to date across all platforms.
Orange Logic webhooks use a publish-subscribe (pub/sub) messaging pattern. When an asset is created, edited (and saved), or deleted, Orange Logic sends an HTTP POST request to the external application. The POST request contains information about the change to the asset.
Webhook process
The Orange Logic platform can send webhooks but cannot receive them.
Notes
- Orange Logic webhooks are deactivated by default. To activate them, submit a support request.
- By default, Orange Logic is configured with a limited set of basic webhooks that are accessible via API. Additionally, Orange Logic can configure automations that trigger webhooks. For example, you might want to trigger a webhook to fire when a specific asset subtype is created. For more information about custom webhook automations, submit a support request.
Retry behavior
If a webhook fails, Orange Logic uses an internal queue system that attempts to resend the webhook up to five times. Orange Logic can configure the number of retries.
Additionally, every webhook event has a unique ID. If the webhook processes an event but the endpoint returns an error, you can use the webhook's unique ID to ensure you successfully perform the action.
Security Functions
Users need the Webhook subscription Security Function to access the webhook APIs.
Webhook API endpoints
Orange Logic offers the webhook API endpoints described in the table below at the URL [https://{OrangeLogicURL}/webapi/extensibility/webhook/subscription/{API_endpoint}].
Note
For information on the webhook endpoints that are listed below but are not yet detailed in our documentation, go to Administration > Maintenance > APIs >Swagger > Extensibility > WebhookSubscription in the Orange Logic interface.
| HTTP method | API endpoints | Description |
|---|---|---|
| POST | /create_22E_v1 | Create a webhook subscription. |
| POST | /update_22F_v1 | Update a webhook subscription. |
| DELETE | /delete_22G_v1 | Delete a webhook subscription. |
| GET | /getbyid_22H_v1 | Get a webhook description based on the webhook identifier. |
| GET | /getall_22I_v1 | Get a list of all webhook subscriptions in this instance of Orange Logic. |
| POST | /testdelivery_22C_v1 | Get custom text or JSON as the input and attempt to deliver directly to the target URL instead of following the full workflow. Returns the HTTP response, including the Response Code and Response Body. |
| POST | /testpredicates_22D_v1 | Test the predicates of a subscription against the conditions you enter in the API call. Returns the first includePredicate and excludePredicate that match the event information. Also returns whether the subscription will be applied when an event with the same information is triggered. ℹ️ NOTE This webhook requires configuration by Orange Logic. For more information, submit a support request. |
| POST | /triggerevent_22N_v1 | Trigger a new event with the Topic and Data (payload). Tests the full workflow. ℹ️ NOTE This webhook requires configuration by Orange Logic. For more information, submit a support request. |
| POST | /gettopics_220_v1 | List all of the webhook topics in your instance of Orange Logic. |
| POST | /rotatesecret_22P_v1 | Generate a secret key for webhook signatures. |
Information shared via webhook
Header
By default, Orange Logic webhooks include the following header information in the API request:
Host: The webhook hosttraceparentContent-length: The number of characters in the requestContent-type: The type of characters included in the request
Optional information
You can add a signature to ensure that webhooks are secure. This signature is included in the header as x-ol-signature with the encrypted signature as the value.
When you create a webhook, you can add custom information that shares context with users by adding the customHeaders parameter.
Body
The information sent to the webhook URL about the event that triggered the webhook includes:
| Field | Description | Example |
|---|---|---|
EventId | The unique ID of the triggered event. A webhook URL should receive each EventID only once. If an EventID is received multiple times, the notification is a duplicate and can be ignored as long as the first one was processed correctly on the webhook URL side. | 773bdd63-29be-4e77-8f39-fb0b572a7a88 |
Topic | The full event name, which is the topic and the event name. | document.deleted |
EventDateUtc | The date when the event occurred in UTC format. | 2024-12-30T19:18:23.8711593Z |
Data | The payload of the event that triggered the webhook, with the encrypted record id. | {“RecordID": "2QDTWAW4499"} |
Tenant | The system the event occurred on, or the location of the event that triggered the webhook. For example, suppose Mangovations uses two Orange Logic systems. The same webhook URL is used for notifications coming from these two systems, and this code indicates which system the event was triggered on. | ZZ1 |
UserId | The encrypted record ID of the user who triggered the event. | K8OEC0ALO_H |
A webhook event’s headers and body.