--- title: "Webhooks: Quick Start Guide" description: "This guide will help you set up AgentSync webhooks so you can register an endpoint, subscribe to events, confirm delivery, and send test events. The steps below apply to all AgentSync APIs — see ProducerSync API Webhook Events and Contracting API Webhook Events for API-specific event types and payload schemas." url: "https://developer.agentsync.io/webhooks-quick-start-guide" image: "https://developer.agentsync.io/_og/d/c_Ocean.takumi,title_~V2ViaG9va3M6IFF1aWNrIFN0YXJ0IEd1aWRl,description_~VGhpcyBndWlkZSB3aWxsIGhlbHAgeW91IHNldCB1cCBBZ2VudFN5bmMgd2ViaG9va3Mgc28geW91IGNhbiByZWdpc3RlciBhbiBlbmRwb2ludCwgc3Vic2NyaWJlIHRvIGV2ZW50cywgY29uZmlybSBkZWxpdmVyeSwgYW5kIHNlbmQgdGVzdCBldmVudHMuIFRoZSBzdGVwcyBiZWxvdyBhcHBseSB0byBhbGwgQWdlbnRTeW5jIEFQSXMg4oCUIHNlZSBQcm9kdWNlclN5bmMgQVBJIFdlYmhvb2sgRXZlbnRzIGFuZCBDb250cmFjdGluZyBBUEkgV2ViaG9vayBFdmVudHMgZm9yIEFQSS1zcGVjaWZpYyBldmVudCB0eXBlcyBhbmQgcGF5bG9hZCBzY2hlbWFzLg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMxODdFRkYifX19,p_Ii93ZWJob29rcy1xdWljay1zdGFydC1ndWlkZSI,s_Ktfm4FUdwzh0s9Nd.png" --- # Webhooks: Quick Start Guide This guide will help you set up AgentSync webhooks so you can register an endpoint, subscribe to events, confirm delivery, and send test events. The steps below apply to all AgentSync APIs — see [ProducerSync API Webhook Events](https://developer.agentsync.io/producersync-api-webhooks) and [Contracting API Webhook Events](https://developer.agentsync.io/contracting-api-webhooks) for API-specific event types and payload schemas. --- ## [What You Need Before You Start](#what-you-need-before-you-start) An **endpoint URL** - a web address in your system where AgentSync will send webhook notifications (example: `https://api.yourcompany.com/webhooks/agentsync`). - We recommend using a dedicated path per API for clarity, e.g., `/webhooks/psapi` for ProducerSync events or `/webhooks/contracting` for Contracting API events. One endpoint can also receive all events — your handler can route by `event.type`. **No endpoint yet?** Use our [Webhooks Listener Example](https://developer.agentsync.io/webhooks-listener-example) and have a test server running in minutes. --- ## [1\. Get Access to the Webhook Portal](#_1-get-access-to-the-webhook-portal) 1. Contact your AgentSync representative or [AgentSync Support](mailto:support@agentsync.io) to request access. 2. You'll receive a **one-time login link** (valid for 7 days). - Need more time? Request a new link! ## [2\. Register Your Endpoint](#_2-register-your-endpoint) 1. Log into the portal. 2. Navigate to the **Endpoints --> Add Endpoint**. 3. Enter your HTTPS endpoint in the **Endpoint URL** field. 4. Under **Subscribe to events**, choose the event types for your API: - **ProducerSync API**: `producersync.updates_available`, `producersync.npn.activated`, `producersync.npn.deactivated` — or select the high-level `producersync` group for all three. See [ProducerSync API Webhook Events](https://developer.agentsync.io/producersync-api-webhooks). - **Contracting API**: subscribe to the `contract` group (and `hierarchy` for hierarchy events), or individual `contract.*` / `hierarchy.*` event types. See [Contracting API Webhook Events](https://developer.agentsync.io/contracting-api-webhooks). - **Identity API**: subscribe to the `id` group or individual `id.producer.*` event types. See [Identity API Webhook Events](https://developer.agentsync.io/identity-api-webhooks). 5. Click **Create** to save your endpoint. ## [3\. Verify Your Endpoint](#_3-verify-your-endpoint) When you save your endpoint, AgentSync immediately sends a test request to confirm it works. Your endpoint must: - Responds with `200 OK` within **5 seconds**. - Handles retries (AgentSync retries with exponential backoff until a max limit is reached). ## [4\. Test Your Integration](#_4-test-your-integration) You can send test events right from the portal: 1. On the **Endpoints** page, click into your endpoint. 2. Open the **Testing** tab (options should be **Overview**, **Testing**, **Advanced**). 3. Pick an event type from the **Send event** dropdown. 4. Click **Send Example** to send the sample payload. 5. Review delivery under **Message Attempts**. Use test events to: - Validate your setup - Troubleshoot without waiting for live traffic - Train your team on handling webhooks --- ## [Security Considerations](#security-considerations) ### [Signing Secret](#signing-secret) - Each webhook payload is signed with a secret unique to your endpoint. - Use this secret to recompute and validate the signature so you know the request came from AgentSync. - Store secrets securely (e.g., environment variables, not code). - You can find your signing secret on the **Endpoints > Your Endpoint** page ### [Headers](#headers) Each webhook request includes headers to help you validate authenticity: - **`webhook-id`** – Unique identifier for the webhook (repeats if retried). - **`webhook-timestamp`** – Unix timestamp of when the event was sent ([learn more](https://en.wikipedia.org/wiki/Unix_time)). - **`webhook-signature`** – Base64-encoded signature(s) to validate authenticity ([learn more](https://en.wikipedia.org/wiki/Base64)). By checking these values, you can ensure the request is genuinely from AgentSync and prevent replay attacks. ### [Mutual TLS (mTLS) — Optional](#mutual-tls-mtls-optional) For endpoints that need to verify the caller at the TLS layer, you can enable mTLS per endpoint (under the endpoint's **Advanced** tab), in addition to the signature verification above. It's optional — signature verification alone keeps your webhooks secure. - **You provide the credentials.** Upload a PEM-encoded client certificate and private key for the endpoint; for a self-signed receiving server, you can also supply a custom CA certificate. AgentSync never stores or manages your keys. - **You own rotation.** There are no proactive expiry warnings — an expired certificate surfaces only as failed deliveries, and an endpoint is automatically disabled after roughly 5 days of continuous failure, creating a silent gap in delivery. Track expiry dates and rotate ahead of time. - **Validate first.** Test the full handshake with a certificate in a non-production environment before enabling mTLS in production. ### [Best Practices](#best-practices) - Reject events with timestamps older than a few minutes (prevents replay attacks). - Verify the signature against your signing secret before processing. --- ## [Event Payloads](#event-payloads) For event types, payload schemas, and examples specific to each API: - [ProducerSync API Webhook Events](https://developer.agentsync.io/producersync-api-webhooks) - [Contracting API Webhook Events](https://developer.agentsync.io/contracting-api-webhooks)