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 ProducerSync API webhooks, you can:

• Stay up-to-date automatically — You’ll get a webhook event as soon as new NIPR data is available for your monitored producer population. Your system can then trigger a job to pull the updates immediately, so you always have the latest data as quickly as possible.
• React instantly to important changes — Get immediate alerts when a producer is activated or deactivated 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 ProducerSync API (PSAPI) 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

Event Schema

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

• id (string): Unique identifier for the webhook event. Useful for logging, troubleshooting, or avoiding duplicate processing if an event is replayed.
• type (string): The specific event type (e.g., producersync.updates_available). This determines how your system should handle the event.
• timestamp (string, ISO 8601 datetime): The time the event occurred, recorded in UTC. Allows your system to order events chronologically and detect stale or delayed messages.
• data (object): event-specific payload containing details about what changed. The shape of this object depends on the type of event.

💡 Tips:

• activated and deactivated events happen immediately because they’re triggered by your account changes — not by NIPR’s daily update cycle.
• updates_available is tied to the daily NIPR update process.

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 subdomain or path for clarity (e.g., /webhooks/psapi).
• 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.