Webhooks
Receive signed payment-status notifications and integrate configurable checkout callbacks.
On this page
DEUNA webhooks cover two different server-to-server flows: notifications that publish payment-state changes to your backend, and synchronous callbacks that let DEUNA request merchant-specific data or logic during checkout. Choose the flow by what your integration needs to accomplish.
| Flow | When it runs | Use it to |
|---|---|---|
| Order and payment status notification | After a subscribed payment status changes | Update fulfillment, reconciliation, and customer-order state without polling continuously. |
| Dynamic checkout webhook | While checkout is waiting for a merchant response | Apply coupons, calculate tips or taxes, retrieve shipping information, validate data, or run another merchant-specific checkout action. |
Browser redirects, SDK callbacks, and provider-to-DEUNA callbacks are separate integration surfaces. Do not use them as proof of payment or as replacements for these backend flows.
Order and payment status notifications#
Status notifications deliver the latest order snapshot to your backend when the normalized payment status matches an event subscribed for the merchant. These notifications are asynchronous: the payment lifecycle does not wait for your business logic to finish.
payment.<status>, and DEUNA checks the merchant subscription.Configure status delivery
Define the delivery contract for each environment:
| Setting | What to define |
|---|---|
| Destination | The HTTPS endpoint that accepts status notifications. |
| Events | The payment.<status> events required by your order lifecycle. |
| Request contract | Any static headers, URL parameters, and approved payload transformation. |
| Failure handling | The acknowledgement, retry, monitoring, and reconciliation behavior agreed for the integration. |
The available events follow the payment lifecycle documented in Payment workflow and statuses. Event coverage can differ by payment method because not every method supports every payment operation or status.
Default payload
Without a custom payload transformation, DEUNA sends an HTTP POST with Content-Type: application/json and the current order under the order property:
{
"order": {
"token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
"order_id": "merchant-order-123",
"transaction_id": "transaction-456",
"status": "succeeded",
"payment_status": "processed",
"currency": "USD",
"total_amount": 5000,
"payment": {
"data": {
"status": "processed",
"processor": "example_processor",
"external_transaction_id": "processor-789"
}
}
}
}The order can contain the customer, item, amount, payment, processor, fraud, metadata, and custom-field data associated with that transaction. Treat order.payment.data.status as the authoritative payment state, and use order.token, order.order_id, and the applicable transaction identifiers for reconciliation.
A merchant-specific configuration can change the HTTP method, headers, URL parameters, subscribed statuses, and payload shape. If a custom configuration is enabled, implement the exact contract certified for that merchant instead of assuming the default body.
Verify the signature
Current delivery adds an X-Signature header. This replaces older examples that refer to X-Deuna-Signature.
- Read the unmodified request body before a framework parses or reserializes it.
- Apply the HMAC-SHA256 and Base64 verification procedure certified for the delivery flow and environment.
- Compare the calculated value with
X-Signatureusing a constant-time comparison. - Reject the request before processing if the values do not match.
Status notifications and dynamic webhooks do not always sign the same input when payload transformation is enabled. Do not reuse a verifier between those flows until the signed input and key derivation have been confirmed during certification.
Keep private API keys on the server. Never place them in browser code, mobile applications, logs, or webhook responses.
Acknowledge and reconcile
- Verify the signature before trusting the payload.
- Record a deduplication key that includes the order token and event or resulting payment status.
- Return a successful
2xxresponse as soon as the request is durably accepted. - Re-read or reconcile the authoritative order state before fulfillment, cancellation, capture, refund, or another irreversible action.
- Ignore a notification that would move your local record backward from a newer state.
Delivery failures can be retried. Do not assume exactly-once delivery, a fixed retry interval, or arrival in lifecycle order.
Dynamic checkout webhooks#
Dynamic webhooks are synchronous, merchant-specific callbacks. When checkout triggers a configured event, DEUNA sends a signed request to your endpoint, validates the response, applies only the permitted updates, and returns the configured result to checkout.
Dynamic webhooks are enabled and configured as part of the merchant implementation. They are not registered from browser or mobile code.
Configuration and execution flow
Configure the webhook with DEUNA as part of your merchant setup. Agree on the event name, destination, request and response shapes, validation rules, and fields the callback may update. After configuration, checkout can execute the event through the same agreed contract.
If the event is not configured for the merchant and environment, DEUNA does not call your endpoint. Treat a required callback that did not run as a configuration issue during certification.
Configuration capabilities
| Capability | Configuration | Behavior |
|---|---|---|
| Event selection | event_name | Identifies the merchant-specific action. Names support letters, numbers, hyphens, and underscores. |
| Destination | url, http_method | Calls the configured URL with GET, POST, PUT, or PATCH; the default method is POST. |
| Request composition | headers, params, query_params, payload_template | Builds static or order-aware headers and URL values, and can transform the order plus event input into the merchant payload. |
| Response mapping | response_template, response_data | Maps the merchant response into DEUNA's order response shape. The sample response data is required when a response template is configured so the template can be validated before activation. |
| Error and response validation | error_response_template, configured validations | Maps merchant errors and can reject a response that does not satisfy the configured rules. |
| Controlled order mutation | fields_update, custom_fields | Updates only allowlisted order fields and predeclared custom fields. Custom-field results must still satisfy the order's custom-field schema. |
| Checkout response | response_body | Selects order, shipping-rate, shipping-method, or custom-field data to return to checkout. |
| Direct response propagation | propagate_response | Returns the merchant's JSON response directly when the integration needs its own response contract instead of DEUNA order mapping. |
The following excerpt shows the core of a tip calculation definition. It is configuration data, not a request that should be sent from the browser:
{
"event_name": "tip_amount_updated",
"url": "https://merchant.example.com/checkout/tips",
"http_method": "POST",
"fields_update": {
"fields": ["TotalAmount"],
"custom_fields": ["tipAmount"]
},
"response_body": {
"fields": ["Order"],
"custom_fields": ["tipAmount"]
},
"response_template": "{\"order\":{\"total_amount\":{{ .result.total_amount }},\"custom_fields\":{\"tipAmount\":{{ .result.tip_amount }}}}}",
"response_data": "{\"result\":{\"total_amount\":5500,\"tip_amount\":500}}"
}During execution, checkout can supply event-specific input:
{
"data": {
"tip_amount": 500
}
}Without a payload template, the merchant endpoint receives that event data. With a payload template, the template can use both the current order and the event input to build the outbound JSON.
Implement the merchant endpoint
| Concern | Merchant endpoint requirement |
|---|---|
| Repeat execution | Be idempotent for the order token and event name. |
| Response contract | Return JSON that matches the configured response shape or response template. |
| Required fields | Include every configured update field; a missing field causes execution to fail. |
| Latency | Complete within the timeout certified for the integration because checkout waits for the response. |
| Errors | Return a non-2xx response for a business or processing failure, using the configured error shape. |
Dynamic calls include X-Signature and X-Deuna-Operation. When a payload template changes the outbound body, use the signature-verification input agreed during certification; do not assume it is identical to the status-notification contract above.
If response propagation is disabled, the default merchant response can contain order, shipping_rate, and shipping_methods; DEUNA returns only the response fields selected by the configuration. If response propagation is enabled, the merchant response must be valid JSON and is returned directly as the dynamic result.
Practical patterns
Tip calculation example
This example shows the complete checkout-to-merchant path for a configured tip event.
For a tip definition, allowlist only the amount and custom fields that the merchant response is expected to change. The merchant endpoint remains responsible for calculating a consistent order total.