Search
K

Webhooks Overview

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?

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.
  • 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 publishes webhook events for each API. See the API-specific event catalogs for full payload schemas and examples:

All events share the same envelope:

{
  "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

  • Validate signatures — Protects against unauthorized calls.
  • 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

  • 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 for step-by-step instructions.