Browse the reference

Webhooks

8 endpoints

List webhook subscriptions for this household (no secrets)

GET/households/{householdId}/webhooks/subscriptions

read:webhooks

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/webhooks/subscriptions

Response200 · Success

Register an outbound webhook subscription. Secret returned ONCE in the response.

POST/households/{householdId}/webhooks/subscriptions

write:webhooks

Request body

json

{  "url": "https://example.com/hooks/vokse",  "eventTypes": [    "transaction.created",    "budget.overrun"  ]}

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Content-Type: application/json" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/webhooks/subscriptions \     -d '{"url":"https://example.com/hooks/vokse","eventTypes":["transaction.created","budget.overrun"]}'

Response201 · Success

Update url / eventTypes / status of a subscription

PATCH/households/{householdId}/webhooks/subscriptions/{id}

write:webhooks

Parameters

Name	In	Required
id	path	Required

Request body

json

{  "eventTypes": [    "transaction.created"  ]}

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Content-Type: application/json" \     -H "Idempotency-Key: $(uuidgen)" \     -X PATCH https://api.vokse.ai/households/current/webhooks/subscriptions/{id} \     -d '{"eventTypes":["transaction.created"]}'

Response200 · Success

Delete a webhook subscription + every associated delivery

DELETE/households/{householdId}/webhooks/subscriptions/{id}

write:webhooks

Parameters

Name	In	Required
id	path	Required

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X DELETE https://api.vokse.ai/households/current/webhooks/subscriptions/{id}

Response204 · No content

Recent delivery log for this subscription

GET/households/{householdId}/webhooks/subscriptions/{id}/deliveries

read:webhooks

Parameters

Name	In	Required
id	path	Required
limit	query	Required

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/webhooks/subscriptions/{id}/deliveries

Response200 · Success

Queue a past delivery again with its original payload

POST/households/{householdId}/webhooks/subscriptions/{id}/deliveries/{deliveryId}/retry

write:webhooks

Parameters

Name	In	Required
id	path	Required
deliveryId	path	Required

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/webhooks/subscriptions/{id}/deliveries/{deliveryId}/retry

Response202 · Success

Rotate the HMAC signing secret for this subscription (returned ONCE)

POST/households/{householdId}/webhooks/subscriptions/{id}/rotate-secret

write:webhooks

Parameters

Name	In	Required
id	path	Required

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/webhooks/subscriptions/{id}/rotate-secret

Response200 · Success

Send a signed test delivery to this subscription through the real delivery path

POST/households/{householdId}/webhooks/subscriptions/{id}/test

write:webhooks

Parameters

Name	In	Required
id	path	Required

Example request

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/webhooks/subscriptions/{id}/test

Response202 · Success