Skip to content

Webhooks

Jump to bottom
KristofersOzolinsMagebit edited this page Oct 14, 2025 · 1 revision

Webhooks (ACP compatible)

Implemented features checklist

  • Order created/updated webhook dispatch
  • Refund observer integration (credit memo)
  • Configurable webhook URL and secret
  • HMAC-SHA256 signature header Merchant-Signature
  • Request metadata headers: Request-Id, Timestamp
  • Toggle enable/disable via config

On this page

Overview

The module sends webhooks to your endpoint for key order lifecycle events. Webhooks are signed and include request metadata headers. Dispatch is handled centrally by the WebhookService.

Events

  • order_created: Sent after a successful session completion and order placement.
  • order_updated: Sent on order updates, including refunds (credit memos).

Internals:

  • Order created/updated webhooks are prepared via data mappers and dispatched through WebhookService::dispatch.
  • Refunds are hooked via the sales_order_creditmemo_refund event and send order_updated with refund data.

Payload and headers

  • JSON payload shaped by WebhookEventInterface with nested EventDataInterface.
  • Headers set by the service:
    • Merchant-Signature: HMAC-SHA256 of the payload using the configured secret
    • Request-Id: Checkout session ID (AC order id)
    • Timestamp: ISO‑8601 time of dispatch
    • Content-Type: application/json

Security and validation

  • The module computes Merchant-Signature as HMAC‑SHA256 over the raw payload using the configured secret.
  • It includes Request-Id (session id) and Timestamp headers with each request.
  • It sends Content-Type: application/json and the accurate Content-Length.
  • It does not retry failed deliveries automatically (TODO); non‑2xx responses are logged.

Logging

  • Success and failure events are logged via a dedicated logger to /var/log/agentic_commerce_webhooks.log.
  • Critical exceptions during dispatch are logged with context (type, signature, session id).
  • General module actions (non-webhook) log to /var/log/agentic_commerce.log.

Configuration

Admin: Stores -> Settings -> Configuration -> Magebit -> Agentic Commerce -> Agentic Checkout

  • Enable Webhooks
  • Webhook URL
  • Webhook Secret
  • Order Status Map to ACP lifecycle

Troubleshooting

  • No events: ensure Enable Webhooks is on and URL/secret are configured.
  • 4xx from receiver: validate headers and payload; check receiver auth/allowlist.
  • Signature mismatch: verify the exact raw payload and secret used in HMAC.

References

  • ACP Concepts: https://developers.openai.com/commerce/guides/key-concepts

Clone this wiki locally