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

All webhook events in Gravv share a common base structure.

{
  "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": "[email protected]"
  },
  "event_type": "customer.kyc.status.pending",
  "event_category": "customer",
  "event_group_id": "0ff6cf9a-8da0-466d-a71c-714eb4bde248"
}

Every webhook request includes these fields:

Verify webhook signatures

Gravv signs all webhook requests with HMAC-SHA256 to verify authenticity and prevent tampering. You should verify the signature before processing webhook events.

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-Gravv-Signature header of each webhook request.

Verification steps

To verify a webhook signature:

1. Extract the signature from the X-Gravv-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
}

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.
• Collection events: Sent when a payment collection is initiated, fails, or completes successfully.
• Customer KYC events: Sent when a KYC verification is submitted and under review, and when the verification is approved.