{"templateId":"markdown","versions":[{"version":"v2","label":"v2","link":"/products/account-payouts/v2/hmac-signature","default":false,"active":false,"folderId":"7d817e0b"},{"version":"20250101","label":"2025-01-01 (Latest)","link":"/products/account-payouts/hmac-signature","default":true,"active":true,"folderId":"7d817e0b"}],"sharedDataIds":{"sidebar":"sidebar-products/account-payouts/sidebars.yaml","current-catalog-info":"current-catalog-info-/products/account-payouts/openapi"},"props":{"metadata":{"markdoc":{"tagList":["partial","admonition","tabs","tab"]},"custom_product":"Account Payouts","type":"markdown"},"seo":{"title":"HMAC signature","description":"Worldpay for Developers - docs, code examples, resources and tools. Everything you need to build your omnichannel payment solution.","siteUrl":"https://docs.worldpay.com/access","image":"/access/assets/worldpay-logo-light.21b7daf79984773a9fcd7d4fbcb07ae5289dfffd6023c4c3dca720c7058e53dc.33f780a6.svg","keywords":"documentation, api, openapi, sdks, developer, payments, json, payouts, 3ds","jsonLd":{"@context":"https://schema.org","@type":"Organization","url":"https://docs.worldpay.com/access","name":"Worldpay"},"meta":[{"name":"google-site-verification","content":"zjziIKaP3ImsqsfhYnEBnq1R85UabiSwl7HTXuwtZuo"},{"name":"doc_product","content":"Access"},{"name":"doc_category","content":"Documentation"}],"llmstxt":{"hide":false,"sections":[{"title":"Payments API","description":"Payment orchestration API combining fraud assessment, 3ds authentication, SCA exemptions, Worldpay Token creation and a card or wallet based payment.","includeFiles":["products/payments/@20240601/**/*"],"excludeFiles":[]},{"title":"Payment Queries API","description":"Querying your payments data, based on a variety of parameters.","includeFiles":["products/payment-queries/@v1/**/*"],"excludeFiles":[]},{"title":"Card BIN Data API","description":"Provides detailed information about a card.","includeFiles":["products/card-bin/@v1/**/*"],"excludeFiles":[]},{"title":"3DS Authentication API","description":"Request 3DS authentication to protect against fraud, be SCA compliant and to shift liability using this standalone API.","includeFiles":["products/3ds/@v3/**/*"],"excludeFiles":[]},{"title":"FraudSight API","description":"Request a risk assessment and receive a response with an outcome (e.g. lowRisk) using this standalone API.","includeFiles":["products/fraudsight/@v1/**/*"],"excludeFiles":[]},{"title":"Checkout SDK","description":"Integrate using our clientside SDKs for both web and native devices. Benefit from SAQ-A/PCI-SSF compliance.","includeFiles":["products/checkout/web/@v2/**/*","products/checkout/ios/@v4/**/*","products/checkout/android/@v4/**/*","products/checkout/react-native/@v3/**/*","products/checkout/flutter/@v1/**/*"],"excludeFiles":[]},{"title":"Tokens API","description":"Minimizes the exposure of sensitive card details and increases the security of your customer's card details.","includeFiles":["products/tokens/@v3/**/*"],"excludeFiles":[]},{"title":"Card Payments API","description":"Request a card payment using this standalone API, requires separate requests for 3DS, Fraud assessment etc.","includeFiles":["products/card-payments/@v7/**/*"],"excludeFiles":[]},{"title":"Card Verifications API","description":"Verify your customer's card to maximize your authentication rates.","includeFiles":["products/card-verifications/@v6/**/*"],"excludeFiles":[]},{"title":"Account Payouts API","description":"Send funds to your customer's bank accounts and search for payouts using parameters.","includeFiles":["products/account-payouts/@20250101/**/*"],"excludeFiles":[]},{"title":"APMs","description":"Pay using eWallets, bank transfers, direct debits, local card schemes, Postpay and eInvoice/ Buy Now Pay Later.","includeFiles":["products/apms/@20240701/**/*"],"excludeFiles":[]},{"title":"Balance API","description":"Request your account details for a single account or all accounts under an entity.","includeFiles":["products/balance/@20250101/**/*"],"excludeFiles":[]},{"title":"Card Payouts API","description":"Send funds to your customer's cards.","includeFiles":["products/card-payouts/@v4/**/*"],"excludeFiles":[]},{"title":"Events (Webhooks)","description":"Receive status updates from Access Worldpay by setting up a webhook.","includeFiles":["products/events/@v1/**/*"],"excludeFiles":[]},{"title":"FX API","description":"Manage Foreign Exchange (FX) on your payments.","includeFiles":["products/fx/@v1/**/*"],"excludeFiles":[]},{"title":"Hosted Payment Pages (HPP) API","description":"Our low-code option to take payments securely at the lowest PCI compliance level - SAQ A.","includeFiles":["products/hosted-payment-pages/@v1/**/*"],"excludeFiles":[]},{"title":"Money Transfers API","description":"Money Transfer OCTs (Original Credit Transaction) allow funds to be pushed to an eligible card in 30 minutes or less.","includeFiles":["products/money-transfers/@v1/**/*"],"excludeFiles":[]},{"title":"Parties API","description":"Create parties, manage your payout instruments and beneficial owners and carry out identity verification checks.","includeFiles":["products/parties/@20250101/**/*"],"excludeFiles":[]},{"title":"SCA Exemptions API","description":"Maximize a frictionless checkout experience by using issuer data insights to apply exemptions.","includeFiles":["products/sca-exemptions/@v1/**/*"],"excludeFiles":[]},{"title":"Split Payments API","description":"Divide funds from a single payment amongst yourself and your parties/sellers.","includeFiles":["products/split-payments/@20250625/**/*"],"excludeFiles":[]},{"title":"Statements API","description":"Retrieve your account statement and see individual entries for all credits and debits.","includeFiles":["products/statements/@20250101/**/*"],"excludeFiles":[]},{"title":"Transfers API","description":"Transfer funds from source account to target account.","includeFiles":["products/transfers/@20250101/**/*"],"excludeFiles":[]},{"title":"Verified Tokens API","description":"Verified Tokens ensures that your customer's payment details are valid and CIT compliant when creating a token.","includeFiles":["products/verified-tokens/@v3/**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Last updated"]},": 25 June 2026 | ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/account-payouts/changelog/"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Change log"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"hmac-signature","__idx":0},"children":["HMAC signature"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To ensure the webhook body has not been tampered with, you should request an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Event-Signature"]}," header to be sent with your event."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This contains a Hash-based Message Authentication Code (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://en.wikipedia.org/wiki/HMAC"},"children":["HMAC"]},") generated from a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shared secret"]}," and the webhook body itself."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Prerequisite"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Contact your Implementation Manager to enable the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Event-Signature"]}," header and receive the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["signature key"]},". The signature key is unique per merchant and we share it on a secure channel."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"verifying-signature","__idx":1},"children":["Verifying signature"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-1","__idx":2},"children":["Step 1"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Extract the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Event-Signature"]}," HTTP(S) header from the incoming events webhook request."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["can contain multiple signatures (comma separated)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the order of the signatures can change, so always use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["keyId"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"event-signature-examples","__idx":3},"children":["Event signature examples"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Single signature example","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Event-Signature:1/SHA256/XXXXXXXXXX\n"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Multiple signatures example","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Event-Signature:1/SHA256/XXXXXXXXXXXXXX,2/SHA256/YYYYYYYYYYYYYY\n"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"format","__idx":4},"children":["Format"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Event-Signature:{keyId}/{hashFunction}/{signature}\n"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["keyId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Numeric reference for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shared secret"]}," used to sign the message. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["keyId"]}," value changes/increments if a new signature is generated."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hashFunction"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The cryptographic hash function used to create the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://en.wikipedia.org/wiki/HMAC"},"children":["HMAC"]},". Currently supported: ",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://en.wikipedia.org/wiki/SHA-2"},"children":["(SHA256)"]}]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["signature"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hash-based Message Authentication Code ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://en.wikipedia.org/wiki/HMAC"},"children":["(HMAC)"]}," hex output. Generated from the webhook body and shared secret using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hashFunction"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2","__idx":5},"children":["Step 2"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Take the webhook body and shared secret, then use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hashFunction"]}," to generate the HMAC signature."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-3","__idx":6},"children":["Step 3"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Compare your generated HMAC signature from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#step-2"},"children":["Step 2"]}," with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["signature"]}," received in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Event-Signature"]}," header."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Signature outcome"},"children":["Signature outcome"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Follow on action"},"children":["Follow on action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Signatures match"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Respond with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," HTTP(S) status code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Signatures don't match"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Discard the webhook body and return a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," HTTP(S) status code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No signature received (and you are set up for HMAC)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Return a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," HTTP status code."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Recommendation"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["HMAC signature string comparison should be done in constant-time to prevent potential timing attacks."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"hmac-signature-key-renewal","__idx":7},"children":["HMAC signature key renewal"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Due to our security policies, the key we use for generating HMAC signatures is subject to periodic renewal. We will contact you regarding to key renewal process."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The key renewal must allow you to continue to validate signatures during the renewal process without experiencing downtime or incorrectly rejecting notifications. The old key will therefore also be available for signature validation during the renewal process."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We will contact you in order to share the key through a secure channel."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The requests will contain 2 signatures"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["one signature with the current key which is about to be decommissioned"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a second signature with the key previously received which you ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#verifying-signature"},"children":["verify again"]}]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["From the moment the signatures generated with the new key are validated and ready to be used, the old key can be decommissioned."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once your new key is working you must notify your Implementation Manager to confirm the switch from old signatures validation exclusively to the new key. We can then permanently deactivate the old key."]}]}]}]},"headings":[{"value":"HMAC signature","id":"hmac-signature","depth":1},{"value":"Verifying signature","id":"verifying-signature","depth":2},{"value":"Step 1","id":"step-1","depth":3},{"value":"Event signature examples","id":"event-signature-examples","depth":4},{"value":"Format","id":"format","depth":4},{"value":"Step 2","id":"step-2","depth":3},{"value":"Step 3","id":"step-3","depth":3},{"value":"HMAC signature key renewal","id":"hmac-signature-key-renewal","depth":2}],"frontmatter":{"breadcrumbs":{"hide":true},"seo":{"title":"HMAC signature"}},"lastModified":"2026-06-25T15:13:10.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/account-payouts/hmac-signature","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}