Webhooks
Receive real-time event notifications from the Netchex platform
Webhooks let Netchex push events to your system in real time. Instead of polling the API repeatedly, your endpoint receives an HTTPS POST the moment a relevant event occurs — an employee is added, a payroll is confirmed, a benefit enrollment changes.
Webhooks must be enabled for your integration account. Check the webhooksEnabled field in the GET /accounts/me response. Contact your Netchex integration representative to enable them.
How It Works
- Provide your Netchex representative with an HTTPS endpoint URL, a shared secret token, and the event types you want to receive
- Netchex registers your endpoint and sends a one-time validation request — you must respond to it before live events flow
- When an event occurs, Netchex POSTs a JSON payload to your URL
- Respond with
200 OKimmediately to acknowledge receipt; process the event asynchronously - Use the
idfield to handle duplicate deliveries safely
Scoping
Events are scoped to the companies your integration is authorized for. You will only receive events for companies within your access scope — no filtering is needed on your end.
Setup
Webhook configuration is handled by your Netchex integration representative. Provide:
| What | Details |
|---|---|
| Endpoint URL | Publicly accessible HTTPS URL — must support TLS |
| Shared Secret | A token you choose; sent as ?token= on every request so you can verify origin |
| Event Types | The event types you want to receive — all or a subset |
Next Steps
- Endpoint Validation — handle the one-time handshake before events flow
- Event Types — full list of events and their payload fields
- Delivery & Reliability — retry behavior, deduplication, and ordering