Webhooks

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
• Receive notifications when funds arrive in accounts

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": "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
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

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
}