Search
K

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 and Contracting API Webhook Events for API-specific event types and payload schemas.

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 and have a test server running in minutes.

1. Get Access to the Webhook Portal

  1. Contact your AgentSync representative or AgentSync Support 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

  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.
    • Contracting API: subscribe to id.producer or individual id.producer.* event types. See Contracting API Webhook Events.
  5. Click Create to save 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

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

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

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).
  • webhook-signature – Base64-encoded signature(s) to validate authenticity (learn more).

By checking these values, you can ensure the request is genuinely from AgentSync and prevent replay attacks.

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

For event types, payload schemas, and examples specific to each API: