Rotate webhook signing secret

POST

https://devapi.withverifa.com/api/v1/webhooks/endpoints/:endpoint_id/rotate-secret

POST

/api/v1/webhooks/endpoints/:endpoint_id/rotate-secret

$ curl -X POST https://devapi.withverifa.com/api/v1/webhooks/endpoints/wh_abc123/rotate-secret \
>      -H "X-API-Key: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '{}'

1 {
2   "created_at": "2024-01-15T09:30:00Z",
3   "enabled": true,
4   "enabled_events": [
5     "verification.completed",
6     "verification.failed"
7   ],
8   "environment": "live",
9   "id": "wh_abc123",
10   "secret": "whsec_9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a",
11   "updated_at": "2024-01-15T09:30:00Z",
12   "url": "https://webhooks.example.com/verifa",
13   "api_version": "2026-02-01",
14   "attribute_blocklist": [
15     "user.ssn",
16     "user.credit_card"
17   ],
18   "description": "Receives user verification event notifications",
19   "event_filter_conditions": {
20     "verification_status": "completed"
21   },
22   "key_inflection": "camel",
23   "label": "User Verification Webhook"
24 }

Generates a new per-endpoint signing secret (whsec_*) for the webhook endpoint. The previous secret is invalidated immediately — any deliveries signed before the rotation will fail signature verification if they are retried after this point.

The new secret is returned only in this response. Verifa does not store the plaintext, so capture and store it securely.

Authentication

X-API-Keystring

Organization API key. Keys are prefixed with vk_live_ (production) or vk_sandbox_ (sandbox).

Path parameters

endpoint_idstringRequired

Response

Secret rotated. The new secret is included in the response.

created_atdatetime

enabledboolean

enabled_eventslist of strings

Event types this endpoint is subscribed to. Empty means all events.

environmentenum

idstring

secretstring

Per-endpoint HMAC-SHA256 signing secret. Used to verify the X-Verifa-Signature header on outbound webhook deliveries (HMAC over f"{t}.{raw_body}"). Always begins with whsec_. Only returned at endpoint creation and secret rotation — Verifa does not store the plaintext secret after this response, so capture and store it securely.

updated_atdatetime

urlstringformat: "uri"

api_versionstring or null

attribute_blocklistlist of strings

Attribute paths to exclude from webhook payloads.

descriptionstring or null

event_filter_conditionsmap from strings to any

Conditional filters applied before dispatching events to this endpoint.

key_inflectionenum

labelstring or null

Errors

401

Unauthorized Error

404

Not Found Error

Authentication

Path parameters

Headers

Response

Errors