> For the complete documentation index, see [llms.txt](https://help.resouris.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.resouris.com/part-2-running-resouris/webhooks.md).

# Send events to another system

A **webhook** tells another system when something happens in ReSouris, so you do not have to poll for it. A theatre system can learn that next month's roster went live; a workforce dashboard can learn that a leave request was approved.

**Where:** `/ui/admin/webhooks`.

**You need:** `webhook.create` to declare or view one, `webhook.disable` to switch one off. Both are held by `tenant_admin`.

## What you can subscribe to

Three events, and these are the whole list:

| Event              | Fires when                   |
| ------------------ | ---------------------------- |
| `roster.published` | A roster is published.       |
| `roster.archived`  | A roster is archived.        |
| `leave.approved`   | A leave request is approved. |

> ⓘ **The stored value is the contract; the label is not.** `roster.published` is pinned by the v1 API and will not change. The wording you see on screen may be reworded for clarity — build against the value, not the label.

## Declaring one

Each subscription carries a **kind** (one of the three above), a **URL** to POST to, and a **secret reference** — the name of a credential held in the deployment's secret store, not the secret itself. ReSouris never stores the credential value in the tenant database.

Deliveries are POSTed as JSON. If the subscription is configured with an authentication header, that header pair is attached to every request, which is how the receiving system knows the call came from ReSouris.

> ⚠️ **PAYLOADS ARE NOT SIGNED.** There is no HMAC signature over the body to verify. Authenticity rests on the authentication header and on TLS, so treat the endpoint URL and its header value as credentials: anyone who can reach the endpoint and knows the header can forge a delivery. Use HTTPS, and do not put the endpoint on an unauthenticated public path.

> ⚠️ **THE URL IS NOT CHECKED AGAINST AN ALLOWLIST.** Whatever you enter is what gets called. That is deliberate — the deployment decides its own egress rules — but it means a typo delivers your roster events to a stranger, and an internal URL reaches whatever your network lets it reach. Review the URL before saving.

## Retries and failure

The relay distinguishes the two kinds of failure, because they mean different things:

* **`4xx` from your endpoint — not retried.** Your side rejected the request. Retrying an argument your endpoint has already refused only repeats it; fix the endpoint or the subscription.
* **`5xx`, a timeout, or a connection failure — retried.** Your side was unavailable rather than unwilling.

Delivery runs through the notification queue, so a failing endpoint does not block anything in ReSouris; the event is queued, attempted, and retried on the normal schedule. See [Scheduled jobs](/part-2-running-resouris/automations.md).

## Switching one off

**Disable** flips the subscription to `disabled` and stops deliveries. The row survives, so the audit trail still shows that the subscription existed and when it was switched off. Disable rather than asking for a deletion when an integration is retired — a vanished subscription makes an old delivery in somebody else's logs unexplainable.


---

# 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://help.resouris.com/part-2-running-resouris/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.