Webhooks

PaymentHood posts a webhook to your endpoint whenever a payment changes state. Set the URL per payment with webhookUrl, or once for the whole app in the Console.

Payload

The body is small on purpose — it identifies the payment and its new state, and nothing else. Read the payment back from the API for the authoritative detail.

JSON
{
  "payment": {
    "paymentId": 90210,
    "paymentState": "Captured",
    "paymentStateId": 7,
    "referenceId": "order-1001"
  }
}

Delivery and retries

  • Delivery is POST with Content-Type: application/json.
  • Any 2xx response counts as accepted. Anything else — or a timeout — is a failure and the event is retried.
  • Failed events are queued and retried automatically; every attempt is recorded with its status code and error, and is visible in the Console.
  • Sandbox events stop retrying after one hour. Live events keep retrying.
  • Retries and out-of-order delivery are normal. Make your handler idempotent and never move an order backwards.

Authorization header

Independently of signing, you can have PaymentHood send a fixed credential with every webhook. Configure the scheme and parameter in the Console (for example scheme Bearer and a long random token) and we send:

HTTP
Authorization: Bearer YOUR_WEBHOOK_TOKEN

Compare it in constant time, exactly as our own plugins do. This proves the caller knows a shared secret; HMAC signing below additionally proves the body was not altered.