Skip to main content
When you start a background run (a skill run or a workflow run) with a webhook_url, Valendata sends the finished run to that URL as a POST with a JSON body. The body is the same object GET /v1/runs/{run_id} returns.

Delivery

  • webhook_url must be http or https on a public host. Private, loopback, and internal addresses are refused with 422. Use https.
  • Delivery times out after 15 seconds. Redirects are not followed.
  • A network error or a 5xx is retried up to two more times, a few seconds apart. A 4xx is not retried.
  • Return any 2xx quickly, then do your work.

Verify the signature

Every delivery has two headers:
The signature is v1= plus the hex HMAC-SHA256 of "<timestamp>.<raw body>", keyed with your signing secret. Get the secret once with GET /v1/webhooks/secret.
  1. Compute the signature over the raw body. Do not parse and re-serialize the JSON first.
  2. Split the header on commas and compare each value in constant time. Accept if any matches. (For 24 hours after you rotate the secret, it holds v1=<new>,v1=<old>.)
  3. Reject timestamps more than 5 minutes from now, to stop replays.