Overview

Webhooks notify your application when events occur in your Gravv integration. When an event happens, Gravv sends an HTTPS POST request to your webhook endpoint with the event details.

When to use webhooks

Use webhooks to track the status of operations in real time. For example:

• Monitor transfer completion
• Track customer KYC verification status
• Receive notifications when funds arrive in accounts or wallets

Webhook payload structure

Most webhook events in Gravv share a common base structure. External account events are the exception and use a leaner envelope, documented in External account events.

{
  "event_id": "53373f52-2b15-469a-822f-69625a2632b9",
  "tenant_id": "dfa96ede-fc13-43cf-8328-8b910d1cd1d2",
  "timestamp": "2025-10-27T10:11:05Z",
  "event_data": {
    "status": "pending",
    "kyc_type": "basic",
    "tenant_id": "dfa96ede-fc13-43cf-8328-8b910d1cd1d2",
    "customer_id": "0ff6cf9a-8da0-466d-a71c-714eb4bde248",
    "customer_type": "individual",
    "customer_email": "marielle@yopmail.com"
  },
  "event_type": "customer.kyc.status.pending",
  "event_category": "customer",
  "event_group_id": "0ff6cf9a-8da0-466d-a71c-714eb4bde248"
}

Every webhook request includes these fields:

Field	Type	Description
event_id	string	unique identifier for this webhook event
tenant_id	string	your account identifier
transaction_id	string	identifier of the underlying transaction, when the event relates to one
timestamp	string	ISO 8601 timestamp when the event occurred
event_data	object	event-specific data, which varies by event type
event_type	string	type of event, for example, when the transfer status is completed
event_category	string	category of the event, for example, customer
event_group_id	string	groups related events together

Verify webhook signatures

By default, Gravv signs webhook requests with HMAC-SHA256 so you can verify authenticity and detect tampering. Verify the signature before processing an event. If your endpoint is configured to use a different authentication method (basic auth, bearer token, or API key), Gravv sends that credential in place of a signature.

How signature verification works

Gravv generates a signature using:

1. Your webhook secret key from the Dashboard
2. The webhook payload
3. HMAC-SHA256 algorithm

The signature appears in the X-Signature header of each webhook request.

Verification steps

To verify a webhook signature:

1. Extract the signature from the X-Signature header
2. Generate a signature using your secret key and the raw request body
3. Compare the generated signature with the received signature
4. Process the webhook only if the signatures match

Signature generation

The following code sample in Go shows how to generate webhook signatures for verification:

func generateSignature(secretKey string, payload []byte) (string, error) {
    // 1. Initialize HMAC with SHA-256 and the Secret Key
    mac := hmac.New(sha256.New, []byte(secretKey))

    // 2. Hash the Payload
    _, err := mac.Write(payload)
    if err != nil {
        return "", fmt.Errorf("failed to write to hmac: %w", err)
    }

    // 3. Compute the signature (HMAC digest) and encode it as a hexadecimal string
    return hex.EncodeToString(mac.Sum(nil)), nil
}

Delivery, retries, and idempotency

Gravv delivers each event as an HTTPS POST and treats any 2xx response as success. Anything else, including a timeout, is retried.

• Timeout: 30 seconds per attempt.
• Retries: up to 3, with exponential backoff (roughly 2s, then 4s, then 8s).
• At-least-once: your endpoint can receive the same event more than once. Each request carries an X-Event-ID header. Dedupe on it and treat repeats as no-ops.
• Ordering: not guaranteed. Use timestamp and the event's status fields to order events.

Available event types

The event_data object, which contains the event-specific data, contains different fields depending on the event_type. The following are the available event types and their specific data structures:

• Inflow events: Sent when funds are received on-chain into a wallet or account.
• Transfer events: Sent when a transfer is initiated and when it completes successfully.
• External account events: Sent when an external account's asynchronous registration completes, retries, or exhausts its retries.
• Card events: Sent when card transactions occur, cards are funded or withdrawn from, or card status changes.
• Collection events: Sent when a payment collection is initiated, fails, or completes successfully.
• Customer KYC events: Sent when a customer's KYC verification status changes (pending, completed, or failed).