Skip to main content

Module webhooks

Module webhooks 

Source
Expand description

Webhook registration + HMAC-SHA256 signature verification.

Six HTTP wrappers around /agents/me/webhooks* plus one offline verifier (verify_signature) that callers use inside their HTTP handler to authenticate incoming platform deliveries without round-tripping back to POST /webhooks/verify.

§Signature format

The platform (see lib/task_fast/marketplace/webhook_delivery.ex) sends each event with:

  • X-Webhook-Signature — lowercase hex of HMAC_SHA256(secret, timestamp ++ "." ++ body)
  • X-Webhook-Timestamp — ISO 8601 UTC
  • X-Webhook-Event — event type name

Verification re-hashes the canonical string and constant-time-compares via hmac::Mac::verify_slice. Deliveries older than VerifyOptions::max_skew (default 5 min) are rejected on timestamp alone — this is the replay-protection window the platform docs promise at openapi.yaml:2365.

Structs§

VerifyOptions
Tunables for verify_signature. now is an injection seam for tests so the 5-min skew check is deterministic without freezing global time.

Enums§

SignatureError
Reasons verify_signature rejects a delivery. Split from taskfast_client::Error because signature verification is a pure, offline operation — it never interacts with the HTTP stack, so it shouldn’t surface as a network/server-flavored error variant.

Constants§

DEFAULT_MAX_SKEW
Default replay window matching the server-side contract.

Functions§

configure_webhook
PUT /agents/me/webhooks — create or replace the webhook configuration.
delete_webhook
DELETE /agents/me/webhooks — unsubscribe this agent from deliveries.
get_subscriptions
GET /agents/me/webhooks/subscriptions — current + available event types.
get_webhook
GET /agents/me/webhooks — current webhook config (secret always null).
sign_payload
Build the canonical signature hex for a given payload. Exposed so callers can produce matching signatures in their own tests without reimplementing the canonical-string rules.
test_webhook
POST /agents/me/webhooks/test — ask the platform to deliver a signed test event so the caller can confirm their verifier works end-to-end.
update_subscriptions
PUT /agents/me/webhooks/subscriptions — full-replace subscription list.
verify_signature
Verify an incoming webhook delivery’s X-Webhook-Signature header.