Webhooks

Webhooks allow you to push information from Administrate's TMS to an external system, based on triggering events such as record creation and updates. This is useful for integrations that require near-real-time notifications and avoids you from having to periodically poll for updates using our APIs.

For a deep dive into how to discover which events are enabled for Webhooks, and how to create a Webhook and filtered Webhooks see our Core Webhooks documentation

Authentication

Webhooks are encrypted (delivered via TLS) to an endpoint specified during creation.

We currently recommend Basic Auth for authentication, but we also support Hash-Based Message Authentication Code (HMAC) by providing a secret in the Webhook's config during setup.

When we send a payload to the endpoint, we include the config so you can validate that the request is coming from Administrate.

OAuth authentication is not well suited for one-way requests like Webhooks. For example, obtaining refresh tokens is not straightforward and introduces additional complexity and overhead when Basic Auth or HMAC strategy works well.

For more information about setting up Webhooks, see our Core Webhooks documentation on how to set up a Webhook with an example of Basic Auth and HMAC.

Best Practices

Prepare for Scale

Webhooks are sent when updates are performed in the Administrate platform. This can cause the volume of Webhooks sent to fluctuate during times of the day.

If a large number of updates are performed then prepare for a large number of Webhooks to be sent to your external system.

Check timestamps

A series of entity updates during a short time interval will result in the same Webhook firing multiple times. We do not guarantee that your external system will receive these Webhooks in the exact same order of those updates that were performed. The triggered_at timestamp in the payload's metadata indicates when the event was triggered:

{
    "metadata": {
        "triggered_at": "2023-07-19T09:05:13.000000Z",
        "webhook_id": "T3V0Ym91bmRIb29rOjg="
    },
    "payload": {}
}

Your system should ignore any webhooks with a timestamp that is earlier than those already processed.

Have separate apps for handling Webhooks

We recommend having a separate integration for handling Webhooks requests.

For example, if you are planning on using an Event Created Webhook to update an external website, do not have an endpoint on the website. This can prevent our Webhook system from potentially overwhelming the website.

Don't process Webhooks during requests

Our Webhooks system will send the generated payload to an endpoint on your external system. You should store the payload and perform any further action in another process, not during the HTTP request.

This will allow you to handle a large number of requests by taking a lot less time to process the Webhook and be more tolerant of errors if your external app is connecting to another system and it is having issues.