Webhook error responses

HTTP status codes your endpoint should return and how Key handles verification and delivery failures.

Error responses

The verify endpoint returns one of:

Status: 200 · Body: { "message": "Webhook endpoint verified successfully." } · When: Credentials match and the URL is reachable.

Status: 400 · Body: { "error": "invalid_payload", "message": "communityId is required" } · When: Request body is missing or malformed.

Status: 401 · Body: { "error": "invalid_credentials" } · When: Client ID or Secret doesn't match for the given community.

Status: 404 · Body: { "error": "webhook_not_found" } · When: The community doesn't have a webhook configured.

Status: 503 · Body: { "error": "endpoint_unreachable" } · When: Your endpoint didn't respond within 8 seconds during verification.

← Full webhooks reference · developers@key.ai