The Confirmo API features a notification system to keep you informed about important invoice events in real-time:

• Invoice creation
• Status changes
• Payment received and processing
• Refund processing

Notification types

Webhook notifications

When you specify a notifyUrl parameter during invoice creation, Confirmo sends HTTP POST requests to that URL with the current invoice data in JSON format. The request includes:

• Content-Type: application/json header
• Complete invoice model in the request body (identical format to the invoice creation response)

The notification system attempts delivery up to 20 times until receiving a 200 response. After an initial failure, the system waits 1 second before retrying, with the waiting period doubling after each subsequent failure.

If all delivery attempts fail, Confirmo sends an error report via email to the notifyEmail address (if specified) or to the primary merchant email address. This email includes detailed error information and the response from the last failed attempt.

Callback Password

The callback password is a crucial security feature that helps verify webhook authenticity. This autogenerated random alphanumeric string is used to create cryptographic signatures included in every webhook notification header.

The signature is generated and needs to be validated (to ensure that the webhooks do originate from Confirmo and were not forged by someone else).

The signature generation process:

1. Take the complete webhook payload

2. Append the callback password as a suffix

3. Generate a SHA256 hash of the combined string

4. Include the hexadecimal hash in the bp-signature header field of the request/response.

Example

• Callback password: azLlmIpWHM9NJbMe

• Response body:

  Text

  {"address":"P3n6Ul5FsSd59xfbzdD2VN3HHycIddjpc","cryptoUri":"bitcoin:P3n6Ul5FsSd59xfbzdD2VN3HHycIddjpc?amount=0.00779057","createAtTime":1509525927,"serverTime":1509525927,"timeoutTime":1509526226,"id":"inv57dkwrrdw","url":"https://confirmo.net/public/invoice/inv57dkwrrdw","reference":"{\"customerEmail\":
    \"[email protected]\", \"orderNumber\": 123, \"customerName\": \"Customer
    Name\"}","returnUrl":"http://yourEShop.com/thankYourForYourOrder","notifyUrl":"https://yourEShop.com/orderReceived","notifyEmail":"[email protected]","product":{"name":"pName","description":"pDesc"},"status":"active","rate":{"currency":"EUR","currencyX":"BTC","rate":"6418.02"},"txids":[],"invoice":{"amount":"50.00","currency":"EUR"},"crypto":{"amount":"0.00779057","currency":"BTC"},"invoiceSettlements":[],"refunds":[],"paid":{"amount":"0.00000000","currency":"BTC","diff":"-0.00779057"},"flags":{"split":false,"autoUnderpayment":false,"refundable":false},"paidAtTime":0,"completedAtTime":0,"settlementMethodCurrency":"CZK","confirmations":0,"requiredConfirmations":2,"exception":[]}

• SHA256 input:

  Text

  {"address":"P3n6Ul5FsSd59xfbzdD2VN3HHycIddjpc","cryptoUri":"bitcoin:P3n6Ul5FsSd59xfbzdD2VN3HHycIddjpc?amount=0.00779057","createAtTime":1509525927,"serverTime":1509525927,"timeoutTime":1509526226,"id":"inv57dkwrrdw","url":"https://confirmo.net/public/invoice/inv57dkwrrdw","reference":"{\"customerEmail\":
    \"[email protected]\", \"orderNumber\": 123, \"customerName\": \"Customer
    Name\"}","returnUrl":"http://yourEShop.com/thankYourForYourOrder","notifyUrl":"https://yourEShop.com/orderReceived","notifyEmail":"[email protected]","product":{"name":"pName","description":"pDesc"},"status":"active","rate":{"currency":"EUR","currencyX":"BTC","rate":"6418.02"},"txids":[],"invoice":{"amount":"50.00","currency":"EUR"},"crypto":{"amount":"0.00779057","currency":"BTC"},"invoiceSettlements":[],"refunds":[],"paid":{"amount":"0.00000000","currency":"BTC","diff":"-0.00779057"},"flags":{"split":false,"autoUnderpayment":false,"refundable":false},"paidAtTime":0,"completedAtTime":0,"settlementMethodCurrency":"CZK","confirmations":0,"requiredConfirmations":2,"exception":[]}azLlmIpWHM9NJbMe

• SHA256 output as a hex string (and the value of the bp-signature header field):
  0ee2cfd59c72fdc8387859064c9cd18847a43e638327cec2d32fa167ef0f512c

Creating/Deleting

To configure callback passwords, visit Security Settings in the Merchant UI. Only one active callback password is permitted per merchant account. A unique callback password is generated every time and becomes active right away.

Deleting the callback password deactivates the mechanism (bp-signature header is no longer included).

Final Status Check

Security Warning: Never rely exclusively on webhook data for processing payments. Even with the callback password mechanism, a compromised callback password could allow webhook forgery.

Recommended Security Practice: After receiving a webhook notification indicating a final status (such as paid), always verify this status by calling the GET invoice endpoint directly. This endpoint provides the definitive source of truth for invoice status, even if webhook notifications are compromised.

Email notifications

The system supports two types of email notifications in invoice creation request, each serving a different purpose:

Merchant Notifications (notifyEmail)

• Sends basic invoice information in human-readable format to the specified email address
• Notification are sent:
  • When HTTPS notifications fail (see above)
  • When invoice payment is successful
  • When invoice expires and enters exception state
• Important: Do not use customer email addresses here, as those notifications may contain merchant-specific information

Customer Notifications (customerEmail)

• Notifies customers about important invoice status changes:
  • When invoice payment is successful
  • When invoice expires and enters exception state
• Should contain the end-customer's email address only
• Note that the customer email can be set also by end-customer on the public invoice when the invoice is in Confirming state