The Webhook settings page is where carrier, MGA, and wholesaler administrators register HTTPS endpoints that Turris calls automatically whenever a key compliance event happens, so your own CRM, ticketing tool, or data warehouse stays in sync without polling. Each webhook listens for one event type, carries a signed payload your system can verify, and keeps a full delivery history you can audit and replay.

The Webhook settings page lets developers and compliance administrators wire Turris up to their internal systems so those systems react automatically the moment an agency or agent's compliance status flips, a data sync finishes, or a producer agreement is signed. It lives inside the Settings window under the Developer group, alongside API and Integrations.

Who uses it. A platform engineer, integrations developer, or technical operations lead at a carrier, MGA, or wholesaler who owns the connection between Turris and the receiving system.

What you can do here:

The Webhook page lives inside the Settings window, which you can open from anywhere in the platform.

What's visible on the page:

Each row in the webhooks table shows:

Clicking any row replaces the table with the delivery-history view for that webhook.

When you'd do this. You've built or updated a receiving endpoint on your side, you have the HTTPS URL ready, and you know which Turris event category your handler is designed to process.

Warning: The full secret is shown only once, inside the Webhook Created modal. Turris stores it encrypted and never exposes it again. If you lose it, delete the webhook and create a new one to receive a fresh secret.

Tip: Register one webhook per event type rather than one URL that handles everything. It keeps your handler code focused and makes failure patterns easier to diagnose in the delivery history.

Pick the type that matches the event your receiving system is built to handle. Each webhook listens for exactly one type, so register a separate webhook per category when you need more than one.

When you'd do this. You want to audit deliveries to a specific endpoint, confirm Turris is calling it, or investigate why your receiving system did not see an expected event.

Note: If the view shows "No events found for this webhook.", Turris has not yet delivered any event to that endpoint, either because no matching event has occurred or because the webhook was just created.

When you'd do this. A previous delivery failed, you've fixed the bug or outage on your endpoint, and you want Turris to redeliver that specific event instead of waiting for new activity to trigger another one.

Note: Resend creates an additional delivery of the same event. Your handler should be idempotent so it can safely receive the same payload more than once.

When you'd do this. A delivery shows the failed badge and you want to see the HTTP status code or error message your endpoint returned before deciding what to fix.

When you'd do this. You're retiring an integration, replacing the endpoint with a new URL, or rotating the signing secret (which requires recreating the webhook).

Warning: Deletion cannot be undone and invalidates the signing secret. If you later recreate a webhook on the same URL, Turris generates a brand-new secret. To avoid missed events, stand up the replacement webhook first, confirm it is receiving traffic, then delete the old one.

Who can change Webhook settings? Members whose role grants permissions on Webhook settings. Read controls whether the Webhook page and delivery history are visible at all; Create gates Add Webhook; Update gates Resend; Delete gates the row's Delete action.

Can I retrieve the Webhook Secret after closing the confirmation modal? No. Turris stores the secret encrypted and never exposes the full value through the UI again, only the last four characters in the Client Secret column. If the secret is lost, delete the webhook and create a new one to receive a fresh secret.

How do I verify a request really came from Turris? Every request carries two headers: X-Turris-Signature (a hex-encoded HMAC-SHA256 signature) and X-Turris-Timestamp (a Unix timestamp in seconds). To verify, build the signed message as {timestamp}.{raw request body}, compute an HMAC-SHA256 of it using your stored secret as the key, and compare the result to X-Turris-Signature with a timing-safe comparison. Reject any request whose signature does not match.

My signatures never match. What am I missing? The most common mistakes are two: the signing key is the secret decoded from hexadecimal, not the literal characters of the secret string; and the signed body must be the exact raw bytes Turris sent, so verify before any JSON re-serialization that could reorder keys or change whitespace.

What does the request body look like? Each delivery is a JSON object with three top-level fields: webhookType (the event type), upstreamEntityId (your organization's identifier), and payload (the event-specific data). Send a 2xx response as soon as you have accepted it.

How quickly does an event arrive at my endpoint? Entity Compliance Data Synchronized and Producer Agreement Executed events are sent immediately. The two compliance-status-change types are debounced: Turris waits out a roughly one-minute quiet window after the last status change in a sequence before sending a single consolidated payload, with a hard cap that forces delivery during long stretches of continuous activity.

What happens when my endpoint is unreachable? Turris retries failed deliveries automatically with an exponential backoff between attempts, and every attempt appears as an additional row in the delivery history. You can also click Resend on a failed row to trigger an extra retry manually once you have fixed the underlying issue.

Why is the Resend action greyed out? Resend is disabled for events that already have a success status, and hidden entirely from members whose role does not grant the Update permission on Webhook settings.

Can I edit a webhook's URL or type after creation? No. To change either field, delete the webhook and create a new one. The new webhook gets a fresh secret, so update your receiving system before removing the old webhook to avoid missing events in between.

If you have questions about Webhook Settings or encounter any issues, contact our support team at support@turris.com.