Webhooks

DEUNA uses webhooks to send your backend an updated order snapshot when a configured payment or order state changes. The default merchant-facing body contains the order itself. It is not a Stripe-style event envelope.

How it works#

Configure the destination#

For Purchase V2, provide the HTTPS receiver URL in the asynchronous order-notification field shown below:

{
  "order": {
    "order_id": "merchant-order-123",
    "webhook_urls": {
      "notify_order": "https://merchant.example.com/webhooks/deuna/orders"
    }
  }
}

DEUNA stores an order-level URL and can fill a missing value from the merchant setup established during onboarding. The current signed notification flow uses the merchant-level destination and status subscription, so confirm the effective URL for each environment with your TAM. The asynchronous and synchronous webhook URL fields are mutually exclusive for an order.

Order-status notifications do not use a generic webhook-endpoint registration resource. Configure the order field above or use the merchant-level setup agreed with your DEUNA Technical Account Manager (TAM). Dynamic checkout callbacks use the separate API described below.

Supported delivery flows#

Use asynchronous delivery unless DEUNA has explicitly enabled and certified another mode for your integration.

DEUNA creates notification candidates when supported order or payment status values change, when the selected processor changes, and for supported fraud or 3DS decisions. The configured subscription then determines which payment statuses are delivered. Not every state transition produces a webhook.

This mechanism covers purchase updates and the final results of supported asynchronous capture, refund, and void operations. See Payment workflow and statuses for the public statuses and Asynchronous capture, refund, and void for those operation flows.

Dynamic checkout webhooks#

Dynamic checkout webhooks are a separate, synchronous flow. They let a checkout action call a merchant endpoint by event name, validate or transform the response, update selected fields in the tokenized order, and return selected values or the merchant response to the caller.

Use this flow for merchant-specific checkout actions such as tips, loyalty points, donations, and custom coupon behavior. Do not use it as a replacement for asynchronous payment-status delivery.

The effective API Gateway exposes these dynamic-webhook operations:

The execution request can pass event-specific input in data:

{
  "data": {
    "tip_amount": 500
  }
}

DEUNA loads the active configuration for the merchant and event name, then calls the configured merchant URL. The configuration can select the HTTP method, headers, URL parameters, query parameters, payload and response templates, validations, order fields to update, response fields to return, and whether to propagate the merchant response.

The outbound merchant request includes X-Signature and X-Deuna-Operation. Execution is synchronous: merchant timeouts, invalid responses, failed validations, and unsuccessful HTTP responses are returned to the caller. If the merchant has no configuration for the event name, DEUNA returns an empty success response without calling a merchant endpoint.

Dynamic webhook configuration is merchant-specific and can modify an order. Confirm the event name, authentication, allowed fields, templates, validations, timeout, and propagated response with your TAM before enabling it. See the endpoint catalog for the gateway inventory.

Default order-status payload#

The default request is an HTTP POST with Content-Type: application/json and this shape:

{
  "order": {
    "token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
    "order_id": "merchant-order-123",
    "transaction_id": "transaction-456",
    "status": "succeeded",
    "payment_status": "refunded",
    "currency": "USD",
    "total_amount": 5000,
    "payment": {
      "data": {
        "status": "refunded",
        "processor": "example_processor",
        "external_transaction_id": "processor-789"
      }
    }
  }
}

The complete order object can contain the same order, customer, item, amount, payment, processor, fraud, and metadata fields returned in an order response.

• Authoritative payment state: order.payment.data.status
• Stable business identifiers: order.token, order.order_id, and the applicable transaction identifiers

Custom merchant configurations can transform this body. If your receiver does not use the default shape shown above, confirm the exact payload with your TAM.

Authenticate order-status delivery#

The current signed delivery flow sends this request header:

X-Signature: <signature>

The signature is derived with HMAC-SHA256 and Base64 encoding from the JSON payload and merchant credentials.

Validate the exact request body with the credential and verification procedure supplied during onboarding before trusting the payload. Do not rely on alternate header names or undocumented SDK helpers.

Acknowledge and process#

Return HTTP status 200 or another 2xx response as soon as the request is validated and durably queued. You may return an empty body. If you return JSON, DEUNA accepts this response shape:

{
  "status": "success",
  "data": {
    "order_id": "merchant-order-123"
  }
}

Only return a different, non-empty order identifier in this response when you intend DEUNA to replace the merchant order identifier.

Network errors, timeouts, and non-success responses can cause another delivery attempt. Do not depend on a fixed retry interval, and do not assume delivery order. Make processing idempotent and reconcile each snapshot against the latest known payment state.

Test in sandbox#

1. Expose an HTTPS receiver that logs the request headers and unmodified body.
2. Set the asynchronous order-notification URL on a sandbox Purchase V2 request, unless a merchant-level URL is already configured.
3. Complete a payment or an asynchronous capture, refund, or void that changes the payment status.
4. Confirm the payload shape, configured status coverage, signed-header behavior, acknowledgement, and duplicate handling.

The order-status flow does not provide the generic /webhook_endpoints API or a local forwarding CLI command. Test it by producing real sandbox state changes. Test dynamic checkout webhooks through their verified configuration and execution routes.