Docssecurity

Security & Webhook Cryptography

Ensure compliance, sign webhook deliveries, whitelist IP addresses, and secure your programmatic agent credentials.

HMAC-SHA256 Signature Verification

Webhook delivery spoofing is a common vector. To verify that a webhook payload originates from BotPay, bot servers must compute the hex-encoded HMAC-SHA256 signature of the raw request payload using their bot's unique Webhook Secret.

Interactive Webhook Signature Verifier
Verification Status
Awaiting inputs. Click "Verify Signature".

Security Guidelines

  • Secret Rotation: Webhook secret keys should be rotated every 90 days inside the Bot Profile dashboard to prevent leak vectors.
  • Replay Attack Prevention: Validate the `timestamp` field in JSON payloads. Reject messages older than 5 minutes.
  • Daily Spending Caps: AI Agent wallets should enforce spending caps using Circle's agent wallet CLI configuration policies.

Suggested Actions