Skip to main content

Webhooks

In some APIs, we will be asking you to send us an endpoint so that we can callback when we have an update. Webhooks allow us to notify your system when specific events occur, enabling real-time updates and seamless integration.

Webhook Format​

The format of the webhook is as follows:

endpoint_url: "https://yourserver.co/endpoint"
authorization_header: "your_authorization_token"
  • endpoint_url: The URL where we will send the callback request. Make sure this endpoint is accessible and properly configured to handle incoming requests.
  • authorization_header: The authorization token is used to verify that the callback is from Hello Clever. This value should be unique to each webhook and kept confidential.

The authorization_header is something you only share with us, so that when we callback, we can send it back to you and you are sure it's us who's calling your endpoints.

The event will use it as the Authorization header in our callback. We strongly recommend using a different value for authorization_header on each payment request to increase the level of security.

Security Recommendations​

  • Unique Tokens: Use a unique authorization_header for each webhook to enhance security and ensure that each callback is properly validated.
  • HTTPS Only: Make sure your endpoint_url uses HTTPS to guarantee secure data transmission.
  • Idempotency: Ensure that your webhook endpoint can handle multiple callbacks with the same payload. This means implementing idempotent behavior, always returning a 200 OK response even after subsequent calls.

Reliability and Retry Mechanisms​

This call is made by us on a best-effort basis. We implement retry mechanisms to ensure that transient network failures do not affect the ability to call this endpoint. We may call this endpoint more than once with the same payload, so the merchant must ensure that the endpoint is implemented with idempotent behavior.

  • Retry Policy: If the target endpoint does not return HTTP 200, we will retry the webhook call up to 45 times, with a 20-second delay between each attempt.
  • Idempotency: Ensure that your webhook endpoint handles repeated requests safely, without creating duplicate records or side effects.

Implementing these practices will ensure that your integration is reliable, secure, and scalable.