Receiving Events¶

Receive the request¶

Provide an HTTPS endpoint that accepts HTTP POST requests with a UTF-8 JSON body (Content-Type: application/json; charset=utf-8). Validate the configured authentication before acting on the payload, and keep credentials out of application logs.

Legacy authentication uses the configured static x-signature header. Confirm the authentication mode for your account with Blackstone support. Payload versions and signature versions describe separate parts of the protocol.

Process safely¶

Validate the payload and store enough information to reconcile the transaction with your own records. Design processing so receiving the same notification again does not repeat a business action, such as issuing goods or updating an invoice twice. Do not assume notifications arrive in transaction order.

After accepting the notification, return a successful HTTP status in the 2xx range. The response body is ignored. If you queue work for later processing, persist it before acknowledging receipt.

A webhook HTTP acknowledgment confirms receipt by your application. Determine the payment outcome from the transaction information, and reconcile uncertain outcomes against the API before taking further action.

Test your endpoint¶

Use the synthetic examples in the reference to test payload handling locally. Test repeated receipt and unsuccessful processing as well as the successful path. These examples do not initiate payments.

Coordinate an integration test and the applicable delivery policy with Blackstone support before enabling the endpoint for your merchant account.