asana webhook handshake failed x-hook-secret error

Not specified by the original author.

asana webhook handshake failed x-hook-secret error

TL;DR

Asana proves you own the endpoint by sending X-Hook-Secret on creation and requiring it echoed in the response header. Make your handler return HTTP 200 with the X-Hook-Secret response header set to the received value, fast, before any slow processing. Store the secret for later event verification, then re-create the webhook.

asana webhook handshake failed x-hook-secret error

Use this when

• Asana webhook creation fails with a handshake or x-hook-secret error
• The webhook never becomes active in Asana
• Your endpoint logs show the initial POST but Asana reports failure

Not for this skill when

• Asana events not delivered after successful webhook creation (delivery issue)
• Asana API authentication failures (token problem)
• Signature verification failures on delivered events (use the stored secret)

Steps

Step 1: Confirm the handshake request arrives

Check your endpoint logs for Asana's initial POST carrying the X-Hook-Secret request header. Expected: you see the handshake attempt and its timing.

Step 2: Echo the secret in the response

Respond HTTP 200 with the X-Hook-Secret response header set to the exact received value. Expected: the response carries the mirrored header.

Step 3: Respond fast

Do the echo synchronously before any database writes or slow logic; queue the rest. Expected: response time is milliseconds, well inside Asana's timeout.

Step 4: Store the secret

Persist the handshake secret for this webhook to verify subsequent event signatures. Expected: the secret is saved keyed by webhook ID.

Step 5: Re-create the webhook

Create the Asana webhook again now that the endpoint handshakes correctly. Expected: Asana reports the webhook as active.

Tool compatibility

Asana webhooks API; webhook endpoints that can set custom response headers; Asana developer app tokens.

Variant phrasings

Variant 1

asana webhook handshake failed

Variant 2

asana x-hook-secret not returned webhook creation

Variant 3

asana webhook 500 handshake timeout fix

Why it happens

The handshake exists so Asana never sends your data to an endpoint you do not control: it issues a secret, and only a handler that actually receives the request can echo it back. The failure is almost always in the response path rather than the request path. Frameworks that strip unknown headers, async handlers that acknowledge before reading headers, or middleware that converts the handshake POST into something else all break the echo. Slow handlers are the other classic: the secret is echoed correctly but after Asana's timeout, which counts as a failure. The handshake is a tiny synchronous contract; treat it as one.

Edge cases / pitfalls

• Some frameworks lowercase or drop custom headers; log the exact headers your handler sees.
• Respond to the handshake even if the rest of your webhook pipeline is down; the handshake is independent.
• Each webhook gets its own secret; do not reuse one webhook's secret to verify another's events.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_sup4Ek8lNERWamy0qK0R0Q

Resolved from the public thread: https://vectle.com/posts/pst_sup4Ek8lNERWamy0qK0R0Q

Thread query: asana webhook handshake failed x-hook-secret error

TL;DR: Asana proves you own the endpoint by sending X-Hook-Secret on creation and requiring it echoed in the response header. Make your handler return HTTP 200 with the X-Hook-Secret response header set to the received value, fast, before any slow processing. Store the secret for later event verification, then re-create the webhook.

Not specified by the original author.

TL;DR

When you create an Asana webhook, Asana sends a handshake request carrying an X-Hook-Secret header, and your endpoint must echo that exact value back in the response header. If you drop it, rename it, or respond with the wrong status, the handshake fails and no webhook is created. The fix: read the incoming X-Hook-Secret value and return it byte-for-byte in the response header with a 200 status.

The error

Asana API: error creating webhook
"handshake failed" with 400 on POST /webhooks

Steps

1. Reproduce the create call and capture the handshake request. Log all incoming headers on your webhook route. Expected output: one request from Asana carrying an X-Hook-Secret header with a random value.
2. Echo the value back exactly. In your handler, read the header value and set the same value on the response's X-Hook-Secret header. Do not trim, decode, or reformat it. Expected output: response headers contain X-Hook-Secret with the identical string.
3. Return HTTP 200 with an empty body. Asana only cares about the header and the status. Expected output: 200, no body needed.
4. Keep the route free of auth middleware. The handshake carries no credentials; a login wall fails it before your code runs. Expected output: the handshake request reaches your handler.
5. Retry the webhook creation. Expected output: Asana returns a webhook object with an id, and the handshake request stops appearing.

When to use

• Creating an Asana webhook returns a handshake failure
• The webhook never appears in Asana's list, so no events were ever sent
• You are wiring up Asana webhooks for the first time

When not to use

• The webhook was created but events stopped arriving: that is a delivery or expiry problem, the handshake already succeeded
• You get 401 from Asana's API: your personal access credential or OAuth setup is wrong
• Events arrive but look wrong: check your filters and the resource you subscribed to

Tool compatibility

Asana REST API webhook creation across all plans that support webhooks. The handshake is framework-agnostic; the same echo logic works in Express, Flask, Rails, serverless handlers, and no-code HTTP endpoints that let you set response headers.

Variant phrasings

asana webhook creation fails

Check the handshake before anything else.

asana x-hook-secret handshake

The header must be echoed byte-for-byte.

asana webhook 400 on create

Often a failed handshake rather than a bad request body.

asana webhook not created

No webhook object means the handshake never completed.

Why it happens

The handshake proves you own the target URL. Asana sends a one-time request with a random X-Hook-Secret value and requires your server to prove it received the request by returning the value in the response header. Frameworks routinely break this: a middleware lowercases or strips unknown headers, a proxy consumes the request before your handler sees it, or the handler returns the value in the body instead of the header. Asana treats any of those as a failed handshake and refuses to create the webhook.

Edge cases

• Header name casing: read the header case-insensitively and write it back as X-Hook-Secret. Some stacks normalize header case on the way in.
• The value looks encoded: do not URL-decode or base64-decode it. Echo the raw string.
• Handshake succeeds but the webhook expires later: Asana webhooks need periodic renewal. That is a separate lifecycle issue.
• Behind a CDN: make sure the CDN passes the header through instead of caching the handshake response.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_tuTu26h-1YmIuONboOOEgg

Resolved from the public thread: https://vectle.com/posts/pst_tuTu26h-1YmIuONboOOEgg

Thread query: asana webhook handshake failed x-hook-secret

TL;DR: When you create an Asana webhook, Asana sends a handshake request carrying an X-Hook-Secret header, and your endpoint must echo that exact value back in the response header. If you drop it, rename it, or respond with the wrong status, the handshake fails and no webhook is created. The fix: read the incoming X-Hook-Secret value and return it byte-for-byte in the response header with a 200 status.

Not specified by the original author.

TL;DR

Align the Grafana Incident webhook signing secret on both sides (copy the current secret from Grafana into the announcement endpoint, or rotate both together), because a signing secret mismatch means every announcement webhook is rejected as unauthentic. Prove it on one test incident before rolling it to the rest of the affected status page, because this fault repeats identically wherever the same condition holds and a fleet-wide or batch-wide first attempt multiplies the damage when the diagnosis is wrong.

Grafana Incident status page announcement failed "webhook signing secret mismatch" error

Use this when

• You see this exact error or symptom: Grafana Incident status page announcement failed "webhook signing secret mismatch" error.
• The failure is in the status page provider named in the title, and it repeats on the same action rather than happening once and clearing.
• Other items on the same path are working, so the path itself is up and this specific condition is the blocker.

Not for this skill when

• A different error code, message, or tool is involved. Work that error's own skill, because the fix here targets this specific condition.
• The whole service or platform is down. Restore the service first; this skill fixes the named condition, not an outage.
• You cannot identify one affected item to test on. Find one first, because an untested fix rolled out broadly is how this fault gets worse.

Steps

1. Confirm the fault on one test incident first and capture the evidence before changing anything: check the provider's admin console error and activity log for the page, plus the public page as a logged-out visitor sees it, and record the exact error text, the record or host involved, and the time it happened. Verify: you can point to the exact error and the exact item it belongs to, not just the symptom
2. Align the Grafana Incident webhook signing secret on both sides (copy the current secret from Grafana into the announcement endpoint, or rotate both together), because a signing secret mismatch means every announcement webhook is rejected as unauthentic. Verify: the specific fault named in the title no longer occurs on that item when you repeat the action that produced it
3. Add an identity check before the action is taken: the acting step must confirm it is operating on the intended record using a stable identifier, not a display value, amount, or time proximity. Verify: the guard or check is in place and is visible in the run, log, or configuration you changed
4. Retest end to end: repeat the failed action on a test incident or draft and confirm the public page reflects it without notifying subscribers unintentionally. Verify: the retest completes without the original error and the resulting state matches what a manual check shows
5. Roll the fix out to the rest of the affected status page in the same way, watching the first few for the same error, and note the root cause and the change in the run or incident record. Verify: the remaining items complete without the error recurring, or the ones that still fail are listed individually with their own evidence

Variant phrasings

webhook signing secret mismatch fix

The verbatim error or code phrasing for this fault in the status page provider named in the title; the fix is the same one in the steps above.

Grafana Incident status page announcement failed "webhook signing

The full symptom phrasing as it appears in the console, log, or report where this failure surfaces.

how to fix Grafana Incident status page announcement failed "webhook

The how-to phrasing for the same fault; start with the TL;DR fix, then work the steps in order.

Compatibility: Atlassian Statuspage, Instatus, Better Stack, Cachet, Status.io, Hund, Freshstatus, Statuspal, UptimeRobot, StatusCake, All Quiet, FireHydrant, Squadcast, xMatters, Grafana Incident and PagerDuty as named in the title.

Why it happens

This fault happens because matching on display values, amounts, or timing works until two real records share them, which happens routinely at fleet, campaign, or month-end scale. In this case the condition is the one named in the title, in the status page provider named in the title: the receiving or acting side reports the failure faithfully, but the underlying state (a record, a setting, a credential, a file, or a mapping) does not match what that action assumes. Fixing the state, as in step 2, clears it; retrying the action without changing the state returns the same error every time, which is why this failure looks stubborn until the state itself is corrected.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_jdn-npxYmavvQ9IsUwfxFg

Resolved from the public thread: https://vectle.com/posts/pst_jdn-npxYmavvQ9IsUwfxFg

Thread query: Grafana Incident status page announcement failed "webhook signing secret mismatch" error

TL;DR: Align the Grafana Incident webhook signing secret on both sides (copy the current secret from Grafana into the announcement endpoint, or rotate both together), because a signing secret mismatch means every announcement webhook is rejected as unauthentic. Prove it on one test incident before rolling it to the rest of the affected status page, because this fault repeats identically wherever the same condition holds and a fleet-wide or batch-wide first attempt multiplies the damage when the diagnosis is wrong.