Skip to content

DXIM - Extension - improve action signature section#1224

Open
JulienVerbrugge wants to merge 5 commits into
masterfrom
improve-action-signature-docs
Open

DXIM - Extension - improve action signature section#1224
JulienVerbrugge wants to merge 5 commits into
masterfrom
improve-action-signature-docs

Conversation

@JulienVerbrugge

Copy link
Copy Markdown
Contributor

What changed

The ## Signature section was a single sentence with no actionable detail:

It's possible to configure a secret to sign the body of the POST request sent to the destination (SHA-512 protocol).

This PR replaces it with a complete implementation guide based on hands-on experience building a receiver for Action UI Extension calls.

What was added

  • Header name and format: signature: sha512=<hex digest> — the header name was undocumented, which required reading third-party source code to discover.
  • Step-by-step verification algorithm: capture raw body → compute HMAC-SHA512 → strip prefix → timing-safe compare.
  • Warning about raw body capture: most frameworks parse the body before the handler runs; the docs now explain how to intercept bytes before that happens.
  • Code examples in PHP, Node.js, and Python: each snippet shows both the verification function and the framework-specific raw-body capture pattern.
  • Replay attack prevention: the timestamp field already documented in the payload section is now shown in action — how to reject requests older than 5 minutes.
  • Secret rotation pattern: how to accept multiple secrets on the receiver side for zero-downtime key rotation.

Why this matters

Without these details, integrators have to either read the Symfony reference implementation or go back and forth with support to discover:

  1. The header is called signature (not x-akeneo-signature or similar).
  2. The value is prefixed with sha512=.
  3. The raw body — not the serialised parsed object — must be signed.
  4. Timing-safe comparison is required.

All four of these are non-obvious and caused real implementation friction.

JulienVerbrugge and others added 4 commits March 23, 2026 09:37
…amples

The previous section was a single sentence with no actionable detail.
Based on real implementation experience, this PR adds:

- The exact header name (`signature`) and format (`sha512=<hex>`)
- Step-by-step verification algorithm with a warning to capture the raw
  body before JSON parsing
- Working code examples in PHP, Node.js, and Python, each covering the
  raw-body capture gotcha specific to their framework
- Replay attack prevention: how to use the `timestamp` field already
  present in every payload to reject stale requests (5-minute window)
- Secret rotation pattern: accept multiple secrets on the receiver side
  to enable zero-downtime key rotation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@JulienVerbrugge JulienVerbrugge changed the title docs(action): expand signature section with header format, algorithm, and code examples DXIM - Extension - improve action signature section Jun 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant