Our service can send callbacks (or webhooks; we will use the word callback further in this article) when some events happen: invoice or channel created, received a payment, processed a payment, etc.
You can configure callbacks in the "Callbacks (Webhooks)" section in the Dashboard.
Keep in mind: 200 HTTP-code, 10 seconds limit
When you use callbacks be sure that your server always responds with a 200 HTTP-code and do it in less than 10 seconds. If not, our server will retry a callback. Check out our retry strategy to learn how it works.
Validate Callback
When you receive a callback from our service you have to check that this is a valid request. We use signatures for these checks.
Every callback has a header X-Munzen-Signature:
X-Munzen-Signature: request_signature
This header contains a signature, which generates very similar to API Authentication Signature.
Signature Validation Example
Here is an example of how to validate a callback signature:
<?php$secret='your_secret_here';$requestMethod='POST';// always POST for webhooks$requestBody = '{"data":{"id":"0189175b-e5ac-7050-8750-5c3df2663f94","fees":{"processing_channel":{"amount":"0.00208","currency":"ETH"}},"amount":"0.0052","status":"paid","address":"0x166547C06303db50FE610Be067BCC538AcC1849c","currency":"ETH","channel_id":"0189175a-1219-7216-8165-8d08785a93a5","created_at":"2023-07-02T16:07:25.000000Z","address_tag":null,"address_uri":"ethereum:0x166547C06303db50FE610Be067BCC538AcC1849c?amount=0.0052","external_id":"asdqwe123123123","fiat_amounts":{"EUR":{"fee_amount":"3.65","paid_amount":"9.14"},"UAH":{"fee_amount":"146.51","paid_amount":"366.27"},"USD":{"fee_amount":"3.99","paid_amount":"9.98"}},"external_data":null,"status_reason":null,"received_amount":"0.00312","amount_minus_fee":"0.00312","transaction_hash":"0xb810c95bb842c7642da75e620801e12693a517b17f58e92a4d6c143fde285332","received_currency":"ETH","customer_external_id":"3424523dasdasd","transaction_risk_score":7,"conversion_exchange_rate":null},"type":"channel_payment","event":"deposit_completed","timestamp":1688314046}';$stringToSign=$requestMethod.$requestBody;$signature=hash_hmac('sha256',$stringToSign,$secret);
Our IPs
We recommend you white-list our IPs for callbacks and ignore requests from all other IPs. This will be an additional option to secure your callback endpoint. Here are our IPs:
Environment
IPs
Sandbox
34.65.94.128/32
Production
34.65.94.128/32
Retries
As mentioned above, we use retries in the case when we don't receive a 200 HTTP-code from your server. To avoid DDoS on your server from our side, we have an increasing time period for callbacks. Here is how it works:
30 + num ^ 4 + num, where num is the number of retries from 0 to 19.
Full list of retries time periods:
Timeouts
We have 10 seconds limit for every callback response. So if your server will not respond within 10 seconds we will terminate the connection and mark the callback as unsuccessful. We will retry to send this callback again according to our retries policy.
Sometimes callback handlers can contain complex business logic and take time to execute. That's why we recommend you save callback data and respond with 200 HTTP code. And after that process callback data in an async way.
Avoid Double-Spending problem
Sometimes the same callback can be handled by your endpoint a few times. So you need to check every callback and try to log them to avoid double crediting your customer's balances.
