What is a Webhook? A webhook is how Quidax lets your application know in real-time when an event happens on your account. Instead of your app repeatedly asking our servers for updates (API polling), Quidax automatically sends an HTTP POST request with the event details to a URL you provide. Think of them as instant, automated bank alerts for your server. To learn more about webhooks, please see here
Step-by-Step Setup Guide to setting webhooks:
- Log in to your Quidax merchant account.
- Click your username in the navigation bar and go to the API Management tab.
- Click Webhook Configuration.
- Enter your endpoint URL in the Callback URL field.
- Select your Signature Type and provide a Signature Secret.
- Check the Enable "Webhooks" box and click Save.
Webhook Encoding & Security: Quidax supports two types of webhook encoding to ensure your data is secure from malicious payloads:
- Clear Text: Standard, unencrypted webhooks.
- HMAC Signed (Recommended): This method adds a cryptographic signature so you can confirm a request genuinely came from Quidax and wasn't altered in transit.
How to verify incoming webhooks: Quidax sends a quidax-signature header containing a timestamp and a signature. You must recreate the signature on your end using HMAC SHA256 with your Signature Secret over the timestamp and request body. Compare it to the one Quidax sent, if they match, the request is genuine. Refresher for webhook best practices.
Troubleshooting & FAQs
I added my URL, but I’m still not getting responses.
Please check your API settings to confirm that you actually checked the "Enable Webhooks" box after inputting your URL.
Where can I see the webhook response returned by my server?
You can view this from your merchant dashboard. Go to Transactions > navigate to the specific transaction > click on “View Webhooks”. You will be able to view the exact response under the event summary.
What do the HTTP response Codes mean?
- 200 OK: Quidax successfully reached your server and received an acknowledgment.
- 4xx (e.g., 401, 404): Client/Endpoint error. Your URL might be incorrect, or your server is rejecting the request. Please investigate your endpoint.
- 5xx: Server error. Your backend is currently unable to provide a successful response. Please investigate your server health.
What happens if my endpoint fails to respond?
If your server does not provide a 200 OK response, Quidax will retry the delivery up to 5 times over a 24-hour period on this schedule: Immediate, After 1 minute, After 30 minutes, After 1 hour and After 24 hours.
After the 5th attempt, the system stops sending that webhook. However, you can manually replay failed webhooks directly from your Quidax merchant dashboard.
What events actually trigger a webhook?
Quidax sends webhooks for: Wallet Updated, Wallet Address Generated, Deposit Transaction Confirmation, Deposit Successful, Deposit On Hold, Deposit Failed AML, Deposit Rejected, Withdraw Successful, Withdraw Rejected, Order Done, Order Cancelled, Swap Transaction Completed, and Swap Transaction Failed.
Can I receive the same webhook more than once?
Yes. Quidax may send the same event more than once, especially after a retry. Design your endpoint to be idempotent, processing the same webhook twice should never credit a customer twice. Use the transaction ID in the payload to check whether you've already handled that event.
Should I act on the webhook payload alone?
No. Before crediting any value to a customer, make an API call back to Quidax to confirm the transaction status. Never trust the payload blindly, always re-verify it against the live transaction data first. This also protects you from spoofed or tampered requests.
Does a 201 or 204 response count as success?
No. Quidax only accepts an exact 200 responses as acknowledgement. Any other code, including 3xx redirects, 201, or 204, is treated as a failed delivery and will trigger a retry.
Does my callback URL need to be HTTPS?
Yes, this should be enforced, non-TLS requests can leak credentials and are rejected.
Can I test my webhook before going live?
Yes, once you’ve enabled webhooks, whether your account is approved or not, you’d be able to test webhooks.