FireHorse Pay/developersDashboard
Build

Receive payment status updates

Merchant webhooks are asynchronous notifications from Firehorse to your server. Verify raw bytes, deduplicate and confirm the owned transaction.

Configure the destination#

Set the merchant webhook endpoint and a separate webhook secret in Integration → API & Webhooks. Use HTTPS for production. Test Center uses that configured destination rather than an arbitrary URL.

Provider callbacks arrive at Firehorse; merchant webhooks leave Firehorse. They have different payloads and signing configuration. Do not confuse their secrets or history.

Verify before processing#

When a merchant endpoint secret is configured, the signature header is X-FireHorse-Signature: sha256=<hex>. Compute HMAC-SHA256 with that secret over the original raw request body and compare in constant time. Reject a missing or invalid signature when your endpoint requires signing.

Do not parse and reserialize JSON before verification. The API request signing scheme with timestamp and nonce is different from this webhook signature.

Example
import hashlib, hmac

def valid_webhook(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return isinstance(signature, str) and hmac.compare_digest(expected, signature)

Understand the payload#

This is an illustrative subset. transactionId in the merchant webhook is the Firehorse UUID, not the numeric database ID. Additional amount, provider, timestamp and redirectUrl fields may be present.

Prefer creditedAmount and creditedCurrency together, falling back to documented legacy fields only when the new values are absent. A redirectUrl or PROCESSING update does not mean payment succeeded.

Example
{
  "event": "transaction.status.updated",
  "transactionId": "6f1c0c8e-0d62-4a0f-a913-57c6e45d7c21",
  "status": "SUCCESS",
  "type": "DEPOSIT",
  "merchantReference": "order-example-001",
  "requestAmount": 10,
  "requestCurrency": "EUR",
  "creditedAmount": 10,
  "creditedCurrency": "EUR",
  "amountUpdateType": "EXACT"
}

Process duplicates and delayed updates#

  1. Verify the signature and durably store or enqueue the notification before returning a successful 2xx response.
  2. Deduplicate order side effects by transaction UUID and the business action/state. Duplicate delivery must not fulfil an order twice.
  3. Retrieve the owned transaction for the current authoritative state. Do not let an older PROCESSING update undo a confirmed terminal result.
  4. Monitor delivery history and failures. Use callback history for provider inbound evidence and the trace for merchant outbound delivery evidence.

Search documentation