Webhooks
Webhooks Overview
Use webhooks to receive real-time updates from the Curosa platform
Overview
Webhooks allow Curosa to push event notifications to your system in real time. Instead of polling API endpoints repeatedly, you can subscribe to events and process updates as they happen.
How Webhooks Work
- You configure a public HTTPS endpoint in your supplier portal.
- You subscribe that endpoint to one or more event types.
- When an event occurs, Curosa sends a
POSTrequest with a JSON payload to your endpoint. - Your endpoint returns a
2xxresponse to acknowledge successful processing.
Delivery Format
Webhook requests are sent as JSON:
| Property | Value |
|---|---|
| Method | POST |
| Header | Content-Type: application/json |
| Body | Event payload |
The payload structure and event-specific fields are documented in Webhook Events.
Endpoint Requirements
Your webhook endpoint should:
- Be publicly accessible over HTTPS
- Return a
2xxresponse quickly when payloads are accepted - Handle retries safely (idempotent processing recommended)
- Log request failures for operational monitoring
Security Recommendations
- Verify that incoming requests are from trusted infrastructure before processing
- Treat webhook payloads as untrusted input and validate fields
- Avoid performing expensive processing inline; enqueue work where possible
- Use HTTPS only and never expose secrets in webhook URLs
Retry Behavior
If your endpoint returns a non-2xx status code or times out, delivery may be retried according to queue configuration. Design handlers to be idempotent so duplicate deliveries are safe.
Next Steps
- Review supported events in Webhook Events
- Implement event routing based on the
eventfield in the request payload