Webhook Integration
Error Codes
HTTP status codes, error responses, and retry policy for webhook requests.
Error Responses
Your webhook should return appropriate HTTP status codes. Token Vault maps these to user-facing errors:
| HTTP Status | Error Code | Meaning |
|---|---|---|
| 400 | invalid_request | Malformed request body or missing required fields (no retry) |
| 401 | auth_failed | HMAC signature invalid (no retry) |
| 403 | setup_required | Webhook not initialized; run /v1/exchange first (no retry) |
| 410 | code_expired | Exchange code expired (5-minute TTL exceeded, no retry) |
| 410 | code_used | Exchange code already consumed by a previous /v1/exchange call (no retry) |
| 500 | internal_error | Unexpected server error (encryption failure, storage I/O, etc.) |
| 502 | provider_error | OAuth provider returned an error during refresh |
| 502 | upstream_error | Upstream service returned an error during /v1/proxy forwarding |
| 504 | provider_timeout | OAuth provider timed out during refresh |
| 504 | upstream_timeout | Upstream service timed out during /v1/proxy forwarding |
All error responses should include a JSON body:
{
"error": "auth_failed",
"message": "HMAC signature invalid"
}Retry & Timeout Policy
Token Vault uses the following retry strategy for webhook calls:
Timeout: 10 seconds per request (30 seconds for /v1/proxy)
Retries: 2 retries (3 total attempts)
Backoff: 1s after first failure, 3s after second
Attempt 1: Call webhook
Attempt 2: Wait 1s → retry (only on 5xx or timeout)
Attempt 3: Wait 3s → retry (only on 5xx or timeout)
No retry on 4xx errors (400, 401, 403, 410)Extended timeout for /v1/proxy
The /v1/proxy endpoint has a 30-second timeout instead of 10 seconds. This accounts for upstream API latency, since the webhook must make a full HTTP round-trip to the upstream service before responding.