> For the complete documentation index, see [llms.txt](https://docs.pandium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pandium.com/getting-started/integration-patterns/webhooks.md).

# Webhooks

Real-time integrations on Pandium with webhooks: how third-party events reach your integration, how payloads and headers are delivered, and the trade-offs.

Webhooks are how Pandium handles real-time syncing. The direction flips from batch: instead of Pandium polling for changes, the third-party system calls Pandium the moment something happens. You register a URL, the platform posts events to it as they occur, and Pandium hands the payload to your integration to react to, usually by calling another API.

<figure><img src="https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfJn-9R_dn6dvcGNcdk%2Fuploads%2Fgit-blob-9149864ea9b9ea7526c49a981ea9e99ff39d43d6%2F02-webhooks.png?alt=media" alt="A partner platform posts an event to a Pandium webhook handler, which kicks off an integration run that creates or updates records in your API"><figcaption></figcaption></figure>

## How it works on Pandium

Webhook is one of the four trigger types described in [Run Triggers](https://docs.pandium.com/getting-started/anatomy-of-an-integration/run-triggers.md). The integration itself is the same short-lived script as a batch run. What changes is what starts it.

* **Each tenant connector gets its own webhook URL.** When a tenant connects, Pandium generates a unique URL for that tenant and connector. You can find it under Connector Info on the [tenant details page](https://docs.pandium.com/integration-hub/managing-and-updating-tenants-in-the-admin-portal.md). Because the URL is unique and unguessable, only a system you have given it to can trigger runs for that tenant.
* **Subscriptions can be created for you.** For connectors whose API supports creating webhook subscriptions programmatically, Pandium registers the selected events with the third party when the tenant connects, and removes them on disconnect. See the [FAQ](https://docs.pandium.com/reference/faq.md#do-you-support-webhooks-and-event-based-integrations).
* **The payload reaches your script as a file.** Each webhook becomes a run trigger in the `PAN_CTX_RUN_TRIGGERS` environment variable, with the body saved to a file and the request headers included alongside it. If the third party signs its payloads, the signature header is there for your script to verify against the secret it holds.
* **Bursts are consolidated.** Sequential webhooks arriving for the same tenant are bundled into a single run rather than one run per event. If a webhook lands while a run is already in progress, Pandium queues a follow-up run that starts when the current one completes.

## Strengths and trade-offs

Webhooks give you a near-real-time reaction without polling: no wasted calls checking for changes that have not happened, and load scales with event volume rather than tenant count.

The trade-off is that delivery is on the third party's terms. Most platforms deliver at least once, in no guaranteed order, and retry on failure, so your integration needs to be idempotent: processing the same event twice must not create a second record. Because a webhook can be missed, most real-time integrations still pair with a scheduled batch run as a backstop.

## When to use it

Use webhooks when event volume is manageable and you need a fast reaction to something that just happened. It works across any tool that emits webhooks, in any industry.

## Real-world examples

* A new support ticket in a helpdesk tool triggering a sync to a project tracker
* A successful payment in a billing platform updating a customer's account status
* An order created in an ecommerce platform being mirrored into a fulfillment or tax system within seconds

## Related reading

* [Run Triggers](https://docs.pandium.com/getting-started/anatomy-of-an-integration/run-triggers.md)
* [FAQ: Do you support webhooks and event-based integrations?](https://docs.pandium.com/reference/faq.md#do-you-support-webhooks-and-event-based-integrations)
* [Batch and API-Triggered Syncs](https://docs.pandium.com/getting-started/integration-patterns/batch-and-api-triggered-syncs.md)
* [PubSub](https://docs.pandium.com/getting-started/integration-patterns/pubsub.md), for when webhook volume outgrows a single endpoint


---

# 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.pandium.com/getting-started/integration-patterns/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.
