Webhooks overview

Use the Webhooks API to inspect event history and delivery attempts, retrieve individual events, and resend supported events.

How it works

Gravv sends each event to the webhook URL you registered in the Dashboard for the key's environment. Gravv stores every delivery as a record, and these routes let you see and recover them:

• Audit what Gravv sent with the event history, newest first. The event_type filter takes the category, such as transfer. A full type such as transfer.status.completed returns an empty list. An unknown status also returns an empty list.
• Debug a failure with the record. It holds the stored event in payload, attempts, max_retries and your endpoint's last response. Its call history lists each attempt. Neither returns the request headers Gravv sent.
• Recover by reading payload and processing it, or by resending the event. A resend is not signed and carries no X-Signature header. The call returns HTTP 200 with your endpoint's status code. If the resend fails, Gravv retries the event again and signs those retries.

Three ids appear in these routes:

• items[].id in history is the record id, the {id} of the other routes.
• event_id on the record is the event's event_group_id, the same value as the X-Event-ID header.
• payload.event_id is the id your endpoint received. Deduplicate on that one.

These routes return errors as HTTP 400 with {"data":null,"error":"<message>"}, including for an unknown id. A missing or wrong API key still gets 401. A scoped key without webhook:create gets 403 on the resend. Too many requests get 429.

For the event types and their fields, see the event catalogue. For signatures, retries and deduplication, see Set up webhooks.

Endpoints

Authentication

All requests use https://api.gravv.xyz/v1/ and authenticate with the Api-Key header. See Authentication for details.