Store the returned whsec_ value in a secret manager. It is separate from the
API key and must never be exposed in browser code or logs.
3. Receive and verify
Modulus sends a JSON POST with Webhook-Id, Webhook-Timestamp, and
Webhook-Signature. Verify the signature against the exact raw request bytes
before parsing JSON. See Verify signatures.
4. Acknowledge safely
Persist and deduplicate the event by its envelope id, return a 2xx response
quickly, and process fulfillment asynchronously. Non-2xx responses and
timeouts are retried automatically.
Never use your Modulus API key to verify a webhook. Every endpoint has its own
endpoint signing secret.
Was this page helpful?
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Modulus Labs API","colors":{"primary":"#6366F1","light":"#818CF8","dark":"#4F46E5"},"logo":{"light":"https://mintcdn.com/moduluslabsinc/-g2JuykdH6NQMhpI/logo/light.svg?fit=max\u0026auto=format\u0026n=-g2JuykdH6NQMhpI\u0026q=85\u0026s=cdd5299c31d35441c6c6cab379ca0363","dark":"https://mintcdn.com/moduluslabsinc/-g2JuykdH6NQMhpI/logo/dark.svg?fit=max\u0026auto=format\u0026n=-g2JuykdH6NQMhpI\u0026q=85\u0026s=4be7c52f34d4ef4a0ca4b775b9e6792e"},"favicon":"https://mintcdn.com/moduluslabsinc/Hug35GYfKojSeqvX/favicon.svg?fit=max\u0026auto=format\u0026n=Hug35GYfKojSeqvX\u0026q=85\u0026s=65fea7bcc7fbf1163d727867c0623188","api":{"openapi":["api-reference/qr/openapi.json","api-reference/onboarding/openapi.json","api-reference/webhooks/openapi.json","api-reference/payment-webhooks/openapi.json","api-reference/terminal-gateway/openapi.json","api-reference/transaction-reporting/openapi.json","api-reference/ecom/openapi.json"],"playground":{"display":"interactive"},"examples":{"languages":["curl","python","javascript","php","go","java","csharp"]}},"footer":{"socials":{"website":"https://moduluslabs.io"}},"search":{"prompt":"Search Modulus Labs API documentation..."},"contextual":{"options":["copy","view","chatgpt","claude"],"display":"header"},"styling":{"latex":false},"navigation":{"global":{"anchors":[{"anchor":"Support","icon":"envelope","href":"mailto:support@moduluslabs.io"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"moduluslabsinc","hasAudioNarration":false,"actualSubdomain":"moduluslabsinc","customDomains":["docs.moduluslabs.io"],"gitSource":{"type":"github","owner":"modulus-labs-io","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"feedback":{"thumbs":true,"agentFeedback":true},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6ae44ceef49f5b7aedfd0755","clientVersion":"0.0.4128","searchFilterCounts":[{"language":"default","tag":"Documentation","count":51},{"language":"default","tag":"API Reference","count":40},{"language":"default","tag":"Webhooks API","count":27},{"language":"default","tag":"Ecom API","count":17},{"language":"default","tag":"Payment Webhooks","count":16},{"language":"default","tag":"Onboarding API","count":11},{"language":"default","tag":"Terminal Gateway API","count":10},{"language":"default","tag":"QR Ph Webhooks (Legacy)","count":10},{"language":"default","tag":"Transaction Reporting API","count":9},{"language":"default","tag":"Payment Links","count":8}]},"assistantConfig":{"enableStarterQuestions":true,"enableContextualStarterQuestions":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"starterQuestions":[{"_id":"6979644a4ee895505c300ecd","deploymentId":"68ec6943b3c0516c1a13b4bf","questionText":"What is JWE","status":"active","generatedBy":"manual","createdAt":"2026-01-28T01:20:10.549Z","updatedAt":"2026-01-28T01:20:10.549Z","__v":0},{"_id":"6979643f4ee895505c300ea5","deploymentId":"68ec6943b3c0516c1a13b4bf","questionText":"How do I test before going live?","status":"active","generatedBy":"manual","createdAt":"2026-01-28T01:19:59.128Z","updatedAt":"2026-01-28T01:19:59.128Z","__v":0},{"_id":"6979643a4ee895505c300ea0","deploymentId":"68ec6943b3c0516c1a13b4bf","questionText":"What authentication does the API need?","status":"active","generatedBy":"manual","createdAt":"2026-01-28T01:19:54.290Z","updatedAt":"2026-01-28T01:19:54.290Z","__v":0}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"docs/webhooks/payment/quickstart","slug":"/docs/webhooks/payment/quickstart","pageMetadata":{"title":"Payment Webhooks Quickstart","description":"Register an endpoint, retrieve its signing secret, and receive a signed event","href":"/docs/webhooks/payment/quickstart"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Register an endpoint, retrieve its signing secret, and receive a signed event\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,pre:`pre`,span:`span`,..._provideComponents(),...props.components},{CodeBlock,Heading,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(Heading,{level:`2`,id:`1-create-an-endpoint`,children:`1. Create an endpoint`}),`\n`,_jsxs(_components.p,{children:[`Use an API key with `,_jsx(_components.code,{children:`webhooks.write`}),`. Partner- and merchant-scoped keys must\nselect an authorized branch according to your account hierarchy.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`8`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -X`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` POST`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:' \"${'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`MODULUS_API_BASE_URL`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`}/v1/webhook_endpoints\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:' \"X-API-Key: ${'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`MODULUS_API_KEY`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`}\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Content-Type: application/json\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` '{`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"url\": \"https://merchant.example/webhooks/modulus\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"enabled_events\": [\"payment.succeeded\", \"payment.declined\", \"payment.failed\", \"payment.expired\"],`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"description\": \"Production payment events\"`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` }'`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Save the returned endpoint `,_jsx(_components.code,{children:`id`}),`.`]}),`\n`,_jsx(_components.p,{children:`The create response does not include a signing secret. Retrieve it through the\ndedicated endpoint in the next step.`}),`\n`,_jsx(Heading,{level:`2`,id:`2-retrieve-the-signing-secret`,children:`2. Retrieve the signing secret`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:' \"${'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`MODULUS_API_BASE_URL`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\"}/v1/webhook_endpoints/${\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`ENDPOINT_ID`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`}/signing_secret\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:' \"X-API-Key: ${'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`MODULUS_API_KEY`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`}\"`})]}),`\n`]})})}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`3`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"signing_secret\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"whsec_dGVzdF9zaWduaW5nX3NlY3JldA==\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Store the returned `,_jsx(_components.code,{children:`whsec_`}),` value in a secret manager. It is separate from the\nAPI key and must never be exposed in browser code or logs.`]}),`\n`,_jsx(Heading,{level:`2`,id:`3-receive-and-verify`,children:`3. Receive and verify`}),`\n`,_jsxs(_components.p,{children:[`Modulus sends a JSON `,_jsx(_components.code,{children:`POST`}),` with `,_jsx(_components.code,{children:`Webhook-Id`}),`, `,_jsx(_components.code,{children:`Webhook-Timestamp`}),`, and\n`,_jsx(_components.code,{children:`Webhook-Signature`}),`. Verify the signature against the exact raw request bytes\nbefore parsing JSON. See `,_jsx(_components.a,{href:`/docs/webhooks/payment/signatures`,children:`Verify signatures`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`4-acknowledge-safely`,children:`4. Acknowledge safely`}),`\n`,_jsxs(_components.p,{children:[`Persist and deduplicate the event by its envelope `,_jsx(_components.code,{children:`id`}),`, return a `,_jsx(_components.code,{children:`2xx`}),` response\nquickly, and process fulfillment asynchronously. Non-`,_jsx(_components.code,{children:`2xx`}),` responses and\ntimeouts are retried automatically.`]}),`\n`,_jsx(Warning,{children:_jsx(_components.p,{children:`Never use your Modulus API key to verify a webhook. Every endpoint has its own\nendpoint signing secret.`})})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Payment Webhooks Quickstart","description":"Register an endpoint, retrieve its signing secret, and receive a signed event","href":"/docs/webhooks/payment/quickstart"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"1. Create an endpoint","slug":"1-create-an-endpoint","depth":2,"children":[]},{"title":"2. Retrieve the signing secret","slug":"2-retrieve-the-signing-secret","depth":2,"children":[]},{"title":"3. Receive and verify","slug":"3-receive-and-verify","depth":2,"children":[]},{"title":"4. Acknowledge safely","slug":"4-acknowledge-safely","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"moduluslabsinc","siteName":"Modulus Labs API","title":"Payment Webhooks Quickstart - Modulus Labs API","contextualStarterQuestions":[{"_id":"6ab350481b8abc8d55d662aa","deploymentId":"68ec6943b3c0516c1a13b4bf","questionText":"How do I create a webhook endpoint?","status":"active","generatedBy":"contextual","path":"docs/webhooks/payment/quickstart","createdAt":"2026-09-23T04:06:32.006Z","updatedAt":"2026-09-23T04:06:32.006Z","__v":0},{"_id":"6ab350481b8abc8d55d662ab","deploymentId":"68ec6943b3c0516c1a13b4bf","questionText":"Where do I find the signing secret?","status":"active","generatedBy":"contextual","path":"docs/webhooks/payment/quickstart","createdAt":"2026-09-23T04:06:32.006Z","updatedAt":"2026-09-23T04:06:32.006Z","__v":0},{"_id":"6ab350481b8abc8d55d662ac","deploymentId":"68ec6943b3c0516c1a13b4bf","questionText":"How do I verify webhook signatures?","status":"active","generatedBy":"contextual","path":"docs/webhooks/payment/quickstart","createdAt":"2026-09-23T04:06:32.006Z","updatedAt":"2026-09-23T04:06:32.006Z","__v":0}],"navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-09-23T04:06:25.215Z","originalFileLocation":"docs/webhooks/payment/quickstart.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Register an endpoint, retrieve its signing secret, and receive a signed event\">\u003cmeta data-mint-head name=\"application-name\" content=\"Modulus Labs API\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/moduluslabsinc/b12xWXezBf3lDUti/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/moduluslabsinc/b12xWXezBf3lDUti/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/moduluslabsinc/b12xWXezBf3lDUti/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/moduluslabsinc/b12xWXezBf3lDUti/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/moduluslabsinc/b12xWXezBf3lDUti/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/moduluslabsinc/b12xWXezBf3lDUti/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/moduluslabsinc/b12xWXezBf3lDUti/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/moduluslabsinc/b12xWXezBf3lDUti/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/moduluslabsinc/b12xWXezBf3lDUti/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Payment Webhooks Quickstart - Modulus Labs API\">\u003cmeta data-mint-head property=\"og:description\" content=\"Register an endpoint, retrieve its signing secret, and receive a signed event\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Modulus Labs API\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.moduluslabs.io/docs/webhooks/payment/quickstart\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://moduluslabsinc.mintlify.site/_mintlify/api/og/v2?division=Payment+Webhooks\u0026amp;title=Payment+Webhooks+Quickstart\u0026amp;description=Register+an+endpoint%2C+retrieve+its+signing+secret%2C+and+receive+a+signed+event\u0026amp;theme=0e23bf0ca39f87857ce30bad\u0026amp;signature=5b3ba9dfd84ec9f8d82098aabbd9905203c060e92cca70ea61be6263dc61ef72\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Payment Webhooks Quickstart - Modulus Labs API\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Register an endpoint, retrieve its signing secret, and receive a signed event\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://moduluslabsinc.mintlify.site/_mintlify/api/og/v2?division=Payment+Webhooks\u0026amp;title=Payment+Webhooks+Quickstart\u0026amp;description=Register+an+endpoint%2C+retrieve+its+signing+secret%2C+and+receive+a+signed+event\u0026amp;theme=0e23bf0ca39f87857ce30bad\u0026amp;signature=5b3ba9dfd84ec9f8d82098aabbd9905203c060e92cca70ea61be6263dc61ef72\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/moduluslabsinc/b12xWXezBf3lDUti/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Modulus Labs API\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#6366F1\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.moduluslabs.io/docs/webhooks/payment/quickstart\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/docs/webhooks/payment/quickstart.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.moduluslabs.io/#organization\",\"name\":\"Modulus Labs API\",\"url\":\"https://docs.moduluslabs.io\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/moduluslabsinc/-g2JuykdH6NQMhpI/logo/light.svg?fit=max\u0026auto=format\u0026n=-g2JuykdH6NQMhpI\u0026q=85\u0026s=cdd5299c31d35441c6c6cab379ca0363\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.moduluslabs.io#website\",\"name\":\"Modulus Labs API\",\"url\":\"https://docs.moduluslabs.io\",\"publisher\":{\"@id\":\"https://docs.moduluslabs.io/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.moduluslabs.io/docs/webhooks/payment/quickstart#webpage\",\"url\":\"https://docs.moduluslabs.io/docs/webhooks/payment/quickstart\",\"name\":\"Payment Webhooks Quickstart\",\"description\":\"Register an endpoint, retrieve its signing secret, and receive a signed event\",\"dateModified\":\"2026-09-23T04:06:25.215Z\",\"isPartOf\":{\"@id\":\"https://docs.moduluslabs.io#website\"},\"breadcrumb\":{\"@id\":\"https://docs.moduluslabs.io/docs/webhooks/payment/quickstart#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.moduluslabs.io/docs/webhooks/payment/quickstart#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Webhooks API\",\"item\":\"https://docs.moduluslabs.io/docs/webhooks/overview\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Payment Webhooks\",\"item\":\"https://docs.moduluslabs.io/docs/webhooks/payment/overview\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Payment Webhooks Quickstart\",\"item\":\"https://docs.moduluslabs.io/docs/webhooks/payment/quickstart\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.moduluslabs.io/docs/webhooks/payment/quickstart#article\",\"headline\":\"Payment Webhooks Quickstart\",\"name\":\"Payment Webhooks Quickstart\",\"description\":\"Register an endpoint, retrieve its signing secret, and receive a signed event\",\"url\":\"https://docs.moduluslabs.io/docs/webhooks/payment/quickstart\",\"mainEntityOfPage\":{\"@id\":\"https://docs.moduluslabs.io/docs/webhooks/payment/quickstart#webpage\"},\"dateModified\":\"2026-09-23T04:06:25.215Z\",\"publisher\":{\"@id\":\"https://docs.moduluslabs.io/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.moduluslabs.io#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Modulus Labs API\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Modulus Labs API\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/docs/webhooks/payment/quickstart.md","siteName":"Modulus Labs API","nav":{"global":{"anchors":[{"anchor":"Support","icon":"envelope","href":"mailto:support@moduluslabs.io"}]},"tabs":[{"tab":"Documentation","groups":[{"group":"Get Started","pages":[{"title":"Introduction","href":""},{"title":"Base URLs","href":"/docs/base-urls"}]},{"group":"QR API","pages":[{"title":"Introduction","href":"/docs/qr/introduction"},{"title":"Quickstart","href":"/docs/qr/quickstart"},{"title":"Authentication","href":"/docs/qr/authentication"},{"title":"Encryption","href":"/docs/qr/encryption"},{"title":"Testing","href":"/docs/qr/testing"},{"title":"Errors","href":"/docs/qr/errors"}]},{"group":"Webhooks API","pages":[{"title":"Webhooks","href":"/docs/webhooks/overview"},{"group":"Payment Webhooks","pages":[{"title":"Payment Webhooks","description":"Receive signed terminal payment events for Payment Links and Payment Intents","href":"/docs/webhooks/payment/overview"},{"title":"Payment Webhooks Quickstart","href":"/docs/webhooks/payment/quickstart"},{"title":"Endpoint Management","description":"Create and manage Payment Webhook endpoints and signing secrets","href":"/docs/webhooks/payment/endpoints"},{"title":"Events and Payloads","href":"/docs/webhooks/payment/events"},{"title":"Verify Signatures","href":"/docs/webhooks/payment/signatures"},{"title":"Retries and Retriggering","href":"/docs/webhooks/payment/retries"}]},{"group":"QR Ph Webhooks (Legacy)","pages":[{"title":"QR Ph Webhooks (Legacy)","href":"/docs/webhooks/qr-ph/overview"},{"title":"QR Ph Webhooks Quickstart (Legacy)","href":"/docs/webhooks/setup"},{"title":"Receiving QR Ph Webhooks (Legacy)","href":"/docs/webhooks/receiving"},{"title":"QR Ph Webhook Payload (Legacy)","href":"/docs/webhooks/payload"}]}]},{"group":"Onboarding API","pages":[{"title":"Introduction","href":"/docs/onboarding/introduction"},{"title":"Quickstart","href":"/docs/onboarding/quickstart"},{"title":"Authentication","href":"/docs/onboarding/authentication"},{"title":"Enums","href":"/docs/onboarding/enums"}]},{"group":"Terminal Gateway API","pages":[{"title":"Introduction","href":"/docs/terminal-gateway/introduction"},{"title":"Authentication","href":"/docs/terminal-gateway/authentication"},{"title":"Concepts","href":"/docs/terminal-gateway/concepts"},{"group":"HTTP API","pages":[{"title":"Quickstart","href":"/docs/terminal-gateway/http/quickstart"}]},{"group":"WebSocket API","pages":[{"title":"Quickstart","href":"/docs/terminal-gateway/websocket/quickstart"},{"title":"Actions","href":"/docs/terminal-gateway/websocket/actions"},{"title":"Notifications","href":"/docs/terminal-gateway/websocket/notifications"}]}]},{"group":"Transaction Reporting API","pages":[{"title":"Introduction","href":"/docs/transaction-reporting/introduction"},{"title":"Quickstart","href":"/docs/transaction-reporting/quickstart"},{"title":"Authentication","href":"/docs/transaction-reporting/authentication"},{"title":"Filtering","href":"/docs/transaction-reporting/filtering"}]},{"group":"Ecom API","pages":[{"title":"Introduction","href":"/docs/ecom/introduction"},{"title":"Errors","href":"/docs/ecom/errors"},{"group":"Payment Links","pages":[{"title":"Introduction","href":"/docs/ecom/payment-links"},{"title":"Quickstart","href":"/docs/ecom/quickstart"},{"title":"Authentication","href":"/docs/ecom/authentication"}]},{"group":"JavaScript SDK","pages":[{"title":"Introduction","href":"/docs/ecom/jssdk/introduction"},{"title":"Quickstart","href":"/docs/ecom/jssdk/quickstart"},{"title":"Card fields","href":"/docs/ecom/jssdk/card-fields"},{"title":"Confirm the payment","href":"/docs/ecom/jssdk/confirm-payment"},{"title":"3D Secure","href":"/docs/ecom/jssdk/3d-secure"}]}]},{"group":"Shared Resources","pages":[{"title":"Overview","href":"/docs/shared-resources"},{"title":"Glossary","href":"/docs/glossary"},{"title":"Testing","href":"/docs/testing"},{"title":"Errors","href":"/docs/errors"},{"title":"Go-live","href":"/docs/production"},{"title":"Build with AI","href":"/docs/build-with-ai"},{"title":"Changelog","href":"/changelog"}]}]},{"tab":"API Reference","pages":[{"title":"API Reference","href":"/api-reference/qr/ping"}]}]},"basePath":"","title":"Payment Webhooks Quickstart - Modulus Labs API","buildId":"dpl_5tKr6cUUeuVJdEZ9JAEY3h4soMJ8","deploymentId":"dpl_5tKr6cUUeuVJdEZ9JAEY3h4soMJ8","dynamics":[],"chunks":[]}
