{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/webhooks/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Security best practices","description":"Start building with the Dixa API","siteUrl":"https://docs.dixa.io/","keywords":"dixa developer hub, api portal starter, api reference docs","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"security-best-practices","__idx":0},"children":["Security best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All requests made by webhooks can be verified to have been sent from the Dixa platform by running a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://en.wikipedia.org/wiki/HMAC"},"children":["Hash-based message authentication code"]}," (HMAC) verification on the signed webhook's payload."," ","For that purpose, we include the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-DIXA-SIGNATURE"]}," header in the webhook which should contain two comma-separated key-value pairs, for example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"\"X-DIXA-SIGNATURE\" : \"t=1689238949803,v1=e217fa759f322839107e2902a16630e6e122418653733ae70f32d1185abcdefg\"\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The value of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["t"]}," represents the timestamp of the webhook and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v1"]}," is the payload signature."," ","To verify this signature, you can concatenate the following values into a string like below:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The value of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["t"]}," (as a string)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The character ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The response payload (JSON body) with the original format (⚠️ without any formatting or whitespace changes - do not parse the payload before verifying it)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Then, using the above concatenated string, apply HMAC verification with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SHA256"]}," function using your subscription ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secret key"]}," (you can copy this value from your webhook's page after creating your subscription)."," ","The resulting signature should match the value of the Dixa signature in the field ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v1"]},"."," ","The secret key is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HEX"]}," encoded and needs to be decoded if used in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HMAC"]},". The output signature in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v1"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HEX"]}," encoded as well."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"headers-and-authentication","__idx":1},"children":["Headers and authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, Dixa will include the following headers when delivering a webhook. These headers cannot be overwritten:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"X-DIXA-SIGNATURE :  [To verify the requests],\nX-DIXA-SUBSCRIPTION-ID : “beabb3e2-3a10-4a44-9a88-9359887a139f” [A Unique Subscription ID]\nContent-Type : “application/json” [Constant]\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Adding a basic authentication header or a token header is also supported in the UI:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/authorization-headers.a09340b5483263381fea7718b130ad587d4c6d910a702f8c09a08daa92d9df25.a97e1638.png","alt":"Additional Headers"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["More details on basic authentication can be read ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization"},"children":["here"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can also add a custom header if the listening system requires different headers than token and basic. First you enable the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["customer header"]}," toggle, and add the key-value pair. An example is Jira which requires ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Automation-Webhook-Token"]}," as the key and your unique API token as the value."]}]},"headings":[{"value":"Security best practices","id":"security-best-practices","depth":1},{"value":"Headers and authentication","id":"headers-and-authentication","depth":2}],"frontmatter":{"seo":{"title":"Security best practices"}},"lastModified":"2026-04-09T11:32:42.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/webhooks/webhooks-security","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}