Skip to main content

Implementing Webhook Services

The API People Webhook Services API enables real-time event delivery to your backend systems through secure and authenticated HTTPS callbacks. The following steps outline how to implement, configure, and validate webhook connectivity in a production-ready way.

1. Build a Secure Webhook Listener​

Begin by developing an HTTPS endpoint on your backend to receive webhook POST requests from API People.

Your endpoint must:

  • Must be publicly accessible over HTTPS using TLS 1.2 or higher.
  • Must use a valid **TLS certificate issued by a trusted Certificate Authority (CA)—**self-signed certificates are not accepted.
  • Should support Basic Authentication if enabled during registration.
  • Must return a 2xx HTTP status code (e.g., 200 OK) to acknowledge successful receipt of the notification.
  • Should implement exception handling and return appropriate error codes (4xx, 5xx) for processing failures.
  • Must validate the HMAC signature using the XSignature and XTimestamp headers to ensure payload authenticity.

2. Register Your Listener​

Once your listener is ready, register it via the Webhook Services API:

  • Use the POST /webhook-listeners endpoint to submit your listener URL and a descriptive nickname.
  • Each URL must be unique—duplicate registrations for the same URL are not permitted.
  • A Webhook Listener ID will be returned upon successful registration.
  • You can retrieve, update, or delete registered listeners via the same API.
POST /webhook-listeners
Host: api.api-people.com
Content-Type: application/json

{
  "url": "https://example.com/webhooks",
  "description": "My ACH & Wire listener"
}

3. Create Event Subscriptions​

With your listener registered, subscribe to the events you want to receive:

  • Use the POST /event-subscriptions endpoint to associate your Webhook Listener ID with a specific event type (e.g., ach.status, acct.status).
  • An event subscription creates a one-to-one mapping between the listener and event type.
  • You cannot subscribe the same listener to the same event type more than once.
POST /event-subscriptions
Host: api.api-people.com
Content-Type: application/json

{
  "listenerId": "<YOUR_LISTENER_ID>",
  "eventType": "ach.status"
}
info

Duplicate event subscriptions are not allowed for the same listener and event type.

4. Test Your Setup​

Before going live, validate your webhook setup using the API People Webhook Testing API:

POST /event-subscriptions/{subscriptionId}/test
Host: api.api-people.com
  • This triggers a sample event to be sent to your webhook listener.
  • If configured correctly, your listener will receive the dummy payload and respond with a 200 OK.

This step ensures that your system can receive, parse, and acknowledge incoming notifications as expected.

Response Timeout

Your listener must respond within 120 seconds of receiving the request. Failure to respond within the timeout window may result in retries or delivery failure.

Receive Live Events​

Once your webhook listener and event subscriptions are active:

  • API People will deliver real-time notifications via HTTPS POST to your endpoint.
  • Each message includes a structured JSON payload along with security headers for signature validation.
  • Your system should log the notificationId, validate the signature, and process the payload according to your business logic.
IP Whitelisting

If your server requires IP allowlisting contact API People Support to receive the official list of IP addresses used for webhook delivery.