Skip to main content

Webhooks

Webhooks enable real-time notifications from CleverReach about account events, such as receiver changes or form updates. Instead of polling the API to see if anything changed, your application receives instant asynchronous HTTP POST requests with application/json payloads exactly when an event occurs.

Overview
  • Purpose: Get notified of changes instantly without constant API checks (push instead of pull).
  • Security: Includes HMAC signature verification and optional payload encryption.
  • Events: See Available Events for a full list of triggerable actions.

Quick Facts for Developers​

  • Payload Format: application/json
  • Response Requirements: Your server must respond with a 2XX status code within 5 seconds. Any other status code or a timeout will be considered a failure.
  • Retries: Failing endpoints will be retried automatically (ensure your logic handles this gracefully).
  • Idempotency: Use the event context to prevent processing duplicate events.
  • Security: All requests can be verified and encrypted to ensure they originate from CleverReach and remain secure. (See Security / Encryption)

Example Payload​

Before you start building, here is an example of what your endpoint will receive:

{
  "event": "receiver.subscribed",
  "timestamp": 1690000000,
  "payload": {
    "email": "user@example.com",
    "list_id": "123456"
  }
}

Getting Started​

  1. Register your endpoint via the API or dashboard.
  2. Review the list of Available Events you can listen for.
  3. Validate and handle the requests (see Examples).
  4. Use a local tunnel like ngrok to receive webhooks locally during development.