Event types
Every delivery uses
{ id, type, createdAt, data }. Treat identifiers and the
current resource read as authoritative because webhook arrival order is not
guaranteed.
1. Create a registration
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 withGround-Event-Id, Ground-Event-Type, and
Ground-Signature headers. Verify the signature against the exact raw request
body before parsing JSON:
2xx response promptly, then process the event asynchronously.
Deduplicate deliveries by Ground-Event-Id.
3. Reconcile the resource
Route ontype 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 withGET /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.
Delivery statuses
Delivery status is separate from the business-operation status inside
data.
For example, a successfully delivered fee-update event can have delivery status
completed while its payload reports the fee update as failed.
5. Delete a registration
CallDELETE /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.