asana webhook handshake failed x-hook-secret

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

Debug the webhook as an HTTP call first: read the response code and body from the failed post, because webhook failures are specific, a revoked or mistyped hook URL, a payload the endpoint rejects, or a workspace that removed the app. Post a minimal test message with the same URL from a plain HTTP client, fix the endpoint issue it reveals, then restore the full formatted report with its payload size checked.

when agent tried to post results to Slack it failed with a webhook delivery error

Use this when

• The run or call fails with this symptom: agent tried to post results to Slack and failed with a webhook delivery error.
• You are working on an agent posting experiment results to a Slack channel and the failure repeats on the same run or configuration.
• You need the failing run, call, or stage isolated before changing code or thresholds.

Not for this skill when

• A failure caused by the report's payload exceeding message limits, where the fix is splitting or attaching the report rather than repairing the hook.
• The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

Steps

1. Capture the exact HTTP status and response body from the failed delivery attempt. Verify: the endpoint's own complaint is known
2. Send a one-line test message to the same hook URL with a plain HTTP client. Verify: the hook's basic health is proven or disproven
3. Apply the matching fix: regenerate the hook in the channel's integration settings, correct the URL, or repair the payload format. Verify: the test message lands in the channel
4. Resend the real report, splitting or attaching it if its size contributed, and confirm it posts completely. Verify: the full report appears in the channel

Variant phrasings

agent post results slack webhook delivery error

The verbatim phrasing.

slack webhook failed agent experiment results debug response

The debug phrasing.

webhook delivery error agent report channel hook revoked

The revoked phrasing.

Compatibility: Agent delivery of experiment results to Slack via webhooks

Why it happens

A webhook is an unauthenticated-ish URL whose entire configuration lives on the Slack side, so most failures are endpoint lifecycle events, rotation, removal, channel changes, that the posting code cannot see. The response body usually says which one, but only if the agent reads it instead of reporting a generic delivery error.

Edge cases / pitfalls

• Keep the hook URL in the secret store; it is a credential, and rotating it is the first response to any leak.
• Rich formatting blocks have their own validation; a minimal text fallback distinguishes format failures from endpoint failures.

Provenance

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

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

Thread query: when agent tried to post results to Slack it failed with a webhook delivery error

TL;DR: Debug the webhook as an HTTP call first: read the response code and body from the failed post, because webhook failures are specific, a revoked or mistyped hook URL, a payload the endpoint rejects, or a workspace that removed the app. Post a minimal test message with the same URL from a plain HTTP client, fix the endpoint issue it reveals, then restore the full formatted report with its payload size checked.