POST/vaults/verify-webhook

Verify Webhook

Outcome - Registers your webhook endpoint for this vault. RoxCustody immediately sends a test POST with an empty JSON body to the URL, signed with your secret; your server must answer with a 2xx status within 10 seconds, otherwise the call fails. Next, choose events with Create Webhook Events. A vault has one webhook.

Body Parameters

urlstringrequiredhttps URLmax(255)

Your HTTPS endpoint that will receive events.

secretstringrequiredmax(255)

A secret you choose. Used to authenticate deliveries (see authMethod). Printable ASCII only; at least 16 characters with HMAC.

authMethodnumber1 or 2

How deliveries are authenticated. 1 = SECRET_HEADER (default, legacy): the secret is sent in the rox-auth-secret header. 2 = HMAC (recommended): each delivery has a Roxcustody-Signature header "t=<unix time>,v1=<signature>", where the signature is HMAC-SHA256(secret, "<t>.<raw body>") in hex; the secret itself is never sent.

Responses

Response attributes

messagestring

Success message

dataobject

Webhook configuration

Show child attributes (9)
idnumber

Webhook ID. Use it in Create/Update Webhook Events.

urlstring

Your HTTPS endpoint

vaultIdnumber

Vault ID

retryCountnumber

Default number of retries for failed deliveries

retryPeriodstring

Default time between retries

authMethodstring

SECRET_HEADER or HMAC

eventsobject

Every event available to this vault type, grouped by category, with subscribed, retryCount and retryPeriod

subscribedEventsCountnumber

Number of events you are subscribed to

eventsDescriptionobject

What each event means

statusnumber

HTTP status code

Was this page helpful?