# Webhook Fundamentals

Several Docs-Dispatcher providers — Universign, Signaturit (eSign) and MySendingBox (postal) — push **inbound webhooks** to Docs-Dispatcher when an event occurs on their side (signature completed, letter delivered, …). Docs-Dispatcher receives, authenticates, logs and (optionally) triggers downstream actions for these events.

This page covers the inbound webhook architecture: what to configure on the provider side, how authentication works, and what Docs-Dispatcher does on receipt.

## Inbound webhook URL pattern

All inbound webhooks reach Docs-Dispatcher at:

```
POST https://api.docs-dispatcher.io/api/webhooks/{service}/providers/{provider}/endpoint.json
```

| Path segment | Allowed values                                                                                           |
| ------------ | -------------------------------------------------------------------------------------------------------- |
| `{service}`  | `esign`, `postal` (others are not wired yet — see [Events Catalog](/docs-dispatcher/webhooks/events.md)) |
| `{provider}` | provider code, e.g. `universign`, `signaturit`, `mysendingbox`                                           |

Configure this URL on the provider side (in their dashboard or via their API) so that events are posted to it.

## Per-provider authentication

Each provider authenticates its webhook calls differently. Docs-Dispatcher verifies the inbound request **before** processing the event.

| Provider     | Mechanism                                                                                                                                                                                                                              |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Universign   | **JWS signature** in the `x-jws-signature` header — verified against Universign's public JWKS at `https://api.universign.com/v1/webhooks/jwks.json` (RSA-PSS-SHA256). Calls with an invalid or missing signature are dropped silently. |
| Signaturit   | **HTTP Basic Auth** with credentials configured server-side under `webhooks.endpoint.auth.*`                                                                                                                                           |
| MySendingBox | **HTTP Basic Auth** with credentials configured server-side under `webhooks.endpoint.auth.*`                                                                                                                                           |

A failed authentication still returns `200 OK` to the provider (so the provider does not retry indefinitely), but the event is **not** processed.

## What happens on receipt

When a webhook is accepted, Docs-Dispatcher:

1. Parses the provider-specific event payload (see per-service catalogs).
2. Looks up the original `BusinessServiceTransaction` that produced the document (matched by the provider's transaction / document ID).
3. Logs the event against that transaction so it appears in your audit trail.
4. Triggers any deferred actions configured on the original request (for example downloading the signed PDF and uploading it to a CRM, in the eSign case).

Step 4 is what makes the asynchronous flow work end to end — by configuring the original dispatch with deferred targets, you can have signed documents archived automatically.

## Where to go next

* [**Events Catalog**](/docs-dispatcher/webhooks/events.md) — full list of supported events per provider
* [**eSign events**](/docs-dispatcher/webhooks/esign.md) — Universign and Signaturit event tables
* [**Postal events**](/docs-dispatcher/webhooks/postal.md) — MySendingBox event table
* [**Async flow recipe**](/docs-dispatcher/how-to-recipes/async-flow.md) — how to wire deferred actions to webhook-driven completion


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.docs-dispatcher.io/docs-dispatcher/webhooks/fundamentals.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.