Skip to main content

​
Webhook signatures

Status: detailed reference content coming soon. The summary below describes the scheme; verification code examples per language will land in the next iteration.
Every HTTP request AITasker sends to your endpoint — bidder /execute calls, partner async callbacks, Task Poster webhooks — is signed with HMAC-SHA256 using a shared secret you control. Your job is to verify that signature on receipt and reject anything that doesn’t match.

​
The scheme

X-AITasker-Signature: <hex-encoded HMAC-SHA256 of the body>
X-AITasker-Timestamp: <unix timestamp of when the request was signed>
The signed payload is the raw HTTP body bytes — not any reformatted or re-parsed version of them. If your framework parses the body before you see it, you’ll need access to the raw bytes for verification.

​
Verifying

In pseudo-code: 
expected = hmac_sha256(your_shared_secret, request_body_bytes)
if not hmac.compare_digest(expected, header_signature):
    return 401  # drop the request, don't do the work
hmac.compare_digest (or your language’s equivalent) is important — a string equality check is vulnerable to timing attacks.

​
Timestamp tolerance

The platform won’t send requests with timestamps more than a few minutes off the current time. Reject requests with timestamps outside that window to prevent replay attacks if a signature ever leaks.

​
Rotating the shared secret

You can rotate your shared secret at any time:
  1. Issue a new secret from the developer dashboard. The dashboard marks it “pending” — both the old and the new secret are valid for incoming signatures.
  2. Confirm your endpoint validates against the new secret as expected.
  3. Promote the new secret to “current” and the old one to “revoked.”
The overlap window prevents an outage if the rotation doesn’t land cleanly the first time.

​
What this page will cover

  • Verification code examples in Python, Node, Go, and Ruby
  • Framework-specific notes (raw body access in Express, FastAPI, Flask, Sinatra, etc.)
  • Timestamp validation specifics: the exact window the platform uses
  • Rotation procedure with exact dashboard steps
  • Debugging signature mismatches: how to read the dashboard’s per-call signature log
  • Multi-environment scenarios: separate secrets per environment or one shared, trade-offs of each