> ## Documentation Index
> Fetch the complete documentation index at: https://docs.royaltyport.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
> Receive events from external services and trigger automations
## Overview
Webhooks let external services — such as DocuSign — push events into Royaltyport. Each webhook endpoint gives you a unique receiver URL and a signing secret; every incoming delivery is verified against that secret before it is accepted. Verified deliveries can then start automations through the **Webhook trigger** — for example: a signed contract arrives from DocuSign, an automation validates it and uploads it into a project's contract pipeline.
Only organization **Admins** can create, change, or delete webhook endpoints. All organization members can view endpoints and their delivery log.
***
## Accessing Webhooks
Navigate to your organization from the Dashboard, then click **Settings** in the navigation.
Click the **Webhooks** tab in the settings sidebar.
***
## Creating a Webhook Endpoint
Give the endpoint a descriptive name, e.g. "DocuSign — signed contracts".
The provider preset fills in the correct verification settings for the sending service:
| Provider | Use for |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **DocuSign** | DocuSign Connect webhooks — signature settings are locked to DocuSign's scheme, and signed PDFs embedded in the payload are extracted automatically |
| **Generic** | Any other service that sends JSON webhooks signed with HMAC-SHA256 — the signature header, encoding, and optional timestamp check are fully configurable under **Advanced verification** |
The signing secret is the shared key used to verify that deliveries genuinely come from the sending service:
| Mode | When to use |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Generate new secret** | The sending service lets you configure your own secret. Royaltyport generates one and shows it once — paste it into the sending service. |
| **Paste from provider** | The sending service issues its own key (DocuSign works this way). Create the key there and paste it here. |
After creating the endpoint, a dialog shows the unique **receiver URL** (and the secret, if generated). **These are shown only once** — copy them immediately and configure the sending service with them.
The receiver URL and signing secret cannot be viewed again after the dialog is closed. If you lose the secret, use **Rotate secret** on the endpoint to set a new one.
***
## Setting up DocuSign
To connect DocuSign, you need admin access to your DocuSign account. The flow: create an HMAC key in DocuSign, create the endpoint in Royaltyport with that key, then point a DocuSign Connect configuration at the receiver URL.
In DocuSign: **Settings (Admin) → Connect → HMAC keys** (Integrations section) and add a key. Copy the key — DocuSign also shows it only once.
Royaltyport verifies DocuSign's first signature header, so the key you paste into Royaltyport must be the **first (or only) active HMAC key** on the DocuSign account.
Create a webhook endpoint with provider **DocuSign** and paste the HMAC key as the secret. Copy the receiver URL from the dialog.
In DocuSign: **Settings (Admin) → Connect → Add Configuration → Custom**, with:
| Setting | Value |
| --------------------------- | --------------------------------------------------------------------------------------------- |
| **URL to Publish** | The receiver URL you copied from Royaltyport |
| **Data Format** | JSON (SIM event delivery, REST v2.1) — not Legacy/XML |
| **Trigger Events** | Envelope Signed/Completed |
| **Include Data** | **Documents** (required — this embeds the signed PDFs). Certificate of Completion is optional |
| **Associated Users/Groups** | All users, or the specific senders whose envelopes should flow in |
| **Logging** | Enabled (recommended for troubleshooting) |
No new signature needed: open the **Publish** tab in DocuSign Connect, select an earlier completed (signed) envelope, and republish it with your new configuration selected. It can take a few minutes before the publish shows up in DocuSign's Connect dashboard; once sent, the delivery appears in the endpoint's delivery log in Royaltyport.
Webhook payloads are limited to \~4 MB, which fits envelopes with roughly 3 MB of PDF documents. Typical signed contracts (1–3 MB) are fine; contact support if your documents are larger.
***
## The Delivery Log
Click **View deliveries** on an endpoint to open its delivery log. Each delivery shows:
| Column | Meaning |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Verification** | Whether the signature check passed. Failed deliveries are rejected and store no payload |
| **Status** | `dispatched` — one or more automations were started · `no_match` — verified, but no active automation is listening on this endpoint · `failed` — something went wrong (the error column explains) |
| **Files** | Number of documents extracted from the payload into secure storage |
| **Runs** | The automation runs this delivery started |
Admins can **Replay** a delivery: it is re-dispatched to the endpoint's automations exactly as if it had just arrived — useful while building an automation, so you never need to re-sign a document to test.
A `no_match` status is expected until an **active** automation with a Webhook trigger is pointed at the endpoint. See [Automation Triggers](/automations/triggers) for connecting webhooks to automations.
***
## Managing Endpoints
| Action | Effect |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Enable / Disable** | A disabled endpoint rejects all deliveries (the sender receives a 404) |
| **Rotate secret** | Replaces the signing secret — generate a new one or paste the provider's new key. Update the sending service at the same time |
| **Delete** | Permanently removes the endpoint and its delivery log. The receiver URL stops working immediately |