Skip to content

POST Process Cashier Webhook

Endpoint

POST /cashier/webhook/{provider}

Command

ProcessCashierWebhook

Authorization

No customer or manager session is required. Security is handled by the payment provider module through webhook signature validation.

Description

Receives an incoming payment provider webhook, passes the raw body and headers to the active payment provider instance, stores a provider event, and updates the linked Cashier transaction.

If the provider confirms a deposit, Cashier credits the trading account and creates a linked Cashier balance operation. Duplicate webhook events with the same event_id are accepted idempotently.

The HTTP layer passes transport data to the payment module as:

Field Description
provider Provider code from URL
path Request path
method Request method
headers_json JSON string built from parsed request headers
raw_body Original HTTP request body string
raw_query Original URL query string without ?
content_type Request Content-Type header value, when present

Request Example

POST /cashier/webhook/praxis
Content-Type: application/json
X-Signature: <provider-signature>

{
  "event_id": "evt_123",
  "payment_id": "px-15-1779270000",
  "status": "approved",
  "amount": 250.0,
  "currency": "USD"
}

Response Example

{
  "event": {
    "id": 21,
    "provider": "praxis",
    "event_id": "evt_123",
    "transaction_id": 15,
    "provider_payment_id": "px-15-1779270000",
    "payload_json": "{\"event_id\":\"evt_123\",\"status\":\"approved\"}",
    "headers_json": "{\"X-Signature\":\"...\"}",
    "signature_status": 1,
    "processing_status": 1,
    "failure_reason": "",
    "created_time": 1779270100,
    "processed_time": 1779270100
  },
  "transaction": {
    "id": 15,
    "status": 3,
    "provider_payment_id": "px-15-1779270000"
  },
  "data": "OK",
  "duplicate": false
}

Notes

  • Cashier tries active runtime instances for the requested provider until one validates and normalizes the webhook.
  • Payment modules are created with their provider config during module creation; webhook requests contain only transport data.
  • Invalid signatures return 401.
  • Confirmed deposits are credited once; repeated event_id values are treated as duplicates.
  • Amount or currency mismatch moves the transaction to manual_review.