Skip to main content
Use gVault webhooks to react to asynchronous API and onchain state changes without polling every resource. Webhooks complement authoritative API and onchain reads; they do not replace them.

1. Create a registration

Store the returned id and secret. The secret is shown only in the create response and is not returned by list or get calls.

2. Verify every delivery

Ground sends JSON with Ground-Event-Id, Ground-Event-Type, and Ground-Signature headers. Verify the signature against the exact raw request body before parsing JSON:
Return a 2xx response promptly, then process the event asynchronously. Deduplicate deliveries by Ground-Event-Id.

3. Reconcile the resource

Route on type or Ground-Event-Type, then use the identifiers in data to read the current resource state. Events can be delayed or delivered more than once, so update local state monotonically and never assume arrival order.

4. Inspect delivery history

List events across the organization with GET /v2/gvaults/webhooks/events, or for one registration with GET /v2/gvaults/webhooks/{id}/events. Use status, attemptCount, deliveredAt, and lastError to reconcile your receiver.

5. Delete a registration

Call DELETE /v2/gvaults/webhooks/{id}. Deletion stops future deliveries; retain your processed-event ledger for audit and deduplication. API reference: create, list registrations, get, list events, and delete.