---
title: "Webhooks Overview"
url: "https://developer.agentsync.io/webhooks-overview"
image: "https://developer.agentsync.io/_og/d/c_Ocean.takumi,title_Webhooks+Overview,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMxODdFRkYifX19,p_Ii93ZWJob29rcy1vdmVydmlldyI,s_tpWeBzaTR0hNlc0U.png"
---

# Webhooks Overview

## [What Are Webhooks?](#what-are-webhooks)

Webhooks are a way for one system to proactively tell another system when something important happens — so you don’t have to keep checking for updates.

Think of them like a notification from your favorite food delivery app:

-   You don’t have to refresh the app to see if your order is on the way.
-   Instead, the app pushes a message to you when the driver picks up your order.

With AgentSync webhooks, you can:

-   **Stay up-to-date automatically** — Get notified as soon as new data is available, so your system can pull updates immediately without polling.
-   **React instantly to important changes** — Get immediate alerts when producer status, compliance data, or contracting records change in your account.

Our webhook service manages **event queuing**, **retries**, and **guaranteed delivery** — so even if your system has a temporary outage, events won’t be lost:

-   **Event queuing** – if your system can’t take the message right away, we hold it in a queue until it can.
-   **Retries** – if delivery fails, we automatically try again (with increasing wait times between attempts).
-   **Guaranteed delivery** – will retry until it’s successfully delivered or reaches a maximum attempt limit. If retries are exhausted, you can replay the event from the portal.

## [How Do Webhooks Work?](#how-do-webhooks-work)

A webhook is simply a message that AgentSync sends to a web address (URL) you set up in your system.

Here's how it works:

-   **You create an endpoint** in your system that can receive incoming HTTP requests, like [https://api.yourcompany.com/webhooks/psapi](https://api.yourcompany.com/webhooks/psapi).
-   **We send JSON data** to that URL whenever something happens.
-   **Your system processes the message** — for example, update a database, trigger a workflow, or send a notification.
-   **Your system confirms receipt** by responding with a success status code (`200 OK` or any `2xx`) within 5 seconds.

Most customers keep things simple by using **one endpoint** for all webhook events. Your system can then sort events by the `event.type` field to decide what to do with each one.

---

## [AgentSync Available Webhook Events](#agentsync-available-webhook-events)

AgentSync publishes webhook events for each API. See the API-specific event catalogs for full payload schemas and examples:

-   [ProducerSync API Webhook Events](https://developer.agentsync.io/producersync-api-webhooks) — compliance data updates, NPN activations and deactivations
-   [Contracting API Webhook Events](https://developer.agentsync.io/contracting-api-webhooks) — contract, contract assignment, and hierarchy changes
-   [Identity API Webhook Events](https://developer.agentsync.io/identity-api-webhooks) — producer identity, address, phone, bank account, pay distribution, and E&O data changes

**All events share the same envelope:**

```json
{
  "id": "evt_12345",
  "type": "producersync.updates_available",
  "timestamp": "2025-08-25T12:00:00Z",
  "data": {}
}
```

-   `id` (_string_): Unique identifier for the webhook event. Repeated on retries — use for deduplication.
-   `type` (_string_): The specific event type. Determines how your system should handle the event.
-   `timestamp` (_string, ISO 8601_): UTC time the event was generated.
-   `data` (_object_): Event-specific payload. Shape depends on the `type` — see the API-specific event catalogs linked above.

## [Best Practices for Using Webhooks](#best-practices-for-using-webhooks)

-   **Validate signatures** — Protects against unauthorized calls.
-   **Enable mTLS on sensitive endpoints** — Optional per-endpoint client-certificate verification on top of signatures. See [Security Considerations](https://developer.agentsync.io/webhooks-quick-start-guide).
-   **Keep endpoint responses fast** — Process events quickly, then handle heavy logic asynchronously.
-   **Log all webhook receipts** — Helps with troubleshooting and replaying.
-   **Use a dedicated path per API** for clarity (e.g., `/webhooks/psapi`, `/webhooks/contracting`).
-   **Test in a non-production environment** before going live.

## [Troubleshooting & Replaying Events](#troubleshooting-replaying-events)

-   **Replay missed events** directly from the portal.
-   **Use test events** to confirm fixes before re-enabling live delivery.
-   **Monitor event logs** for failures and investigate causes.

Typical causes of failures:

-   Endpoint downtime or network errors
-   Long processing times causing timeouts
-   Security/firewall rules blocking inbound requests

**Ready to set up your first webhook?** Follow the [Webhooks Quick Start Guide](https://developer.agentsync.io/webhooks-quick-start-guide) for step-by-step instructions.