Webhooks: Quick Start Guide

This guide will help you set up ProducerSync API (PSAPI) webhooks so you can register an endpoint, subscribe to events, confirm delivery, and send test events.

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/psapi).

• We recommend using the path /webhooks/psapi so it’s clear this endpoint is dedicated to PSAPI events.

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 to request access.
2. You'll recieve 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 what you'd like to receive:
   • producersync.updates_available – Daily signal that new NIPR data is ready.
   • producersync.npn.activated – When a producer is added to your monitored population.
   • producersync.npn.deactivated – When a producer is removed from your monitored population.
   • Or, select the high-level producersync to receive all 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 PSAPI 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.

Example Event Payloads

producersync.updates_available

{
  "data": {
    "runDate": "2025-07-24"
  },
  "id": "12345",
  "timestamp": "2025-07-24T22:51:05.206Z",
  "type": "producersync.updates_available"
}

💡 Tip: Use data.runDate as the value for the updatedSince parameter in your next API call.

producersync.npn.activated

{
  "data": {
    "activatedAt": "2025-07-25T15:53:01.579Z",
    "npn": "123456789"
  },
  "id": "whe_123454321",
  "timestamp": "2025-07-25T15:53:01.579Z",
  "type": "producersync.npn.activated"
}

producersync.npn.deactivated

{
  "data": {
    "deactivatedAt": "2025-07-25T15:53:01.579Z",
    "npn": "123456789"
  },
  "id": "whe_123454321",
  "timestamp": "2025-07-25T15:53:01.579Z",
  "type": "producersync.npn.deactivated"
}