Webhooks

Webhooks allow you to receive real-time notifications about important events in your Vayu account. This document describes the available webhook types and their payload structures.

Available Webhooks

Webhook Type	Description	Trigger Condition
Overage	Notifies when a customer exceeds their provisioned amount for a product	Customer’s consumption exceeds their provisioned amount
Anonymous Customer Created	Notifies when a new anonymous customer is created in the system	Event was sent for a customer that couldn’t exist

Webhook Payloads

Overage Notification

The overage webhook is triggered when a customer exceeds their provisioned amount for a product. The payload includes detailed information about the product consumption.

Payload Structure

{
  "productId": "string",          // The id of the product
  "productName": "string",        // The name of the product 
  "provisionedAmount": "number",  // The amount of units provisioned to the customer
  "consumedAmount": "number",     // The amount of units consumed by the customer
  "usagePercentage": "number",    // The percentage of the provisioned amount that has been consumed
  "hasAccess": "boolean",         // Whether the customer has access to the product based on the provisioned amount
  "remainingAmount": "number",    // The amount of units remaining to consume
  "exceededAmount": "number"      // The amount of units exceeded
}

you can read more about the product consumption type in the get product consumption endpoint page.

Example Payload

{
  "productId": "prod_123456789",
  "productName": "Vayu Product",
  "provisionedAmount": 1000,
  "consumedAmount": 1200,
  "usagePercentage": 120,
  "hasAccess": false,
  "remainingAmount": 0,
  "exceededAmount": 200
}

Anonymous Customer Created

This webhook is triggered when a new anonymous customer is created in the system. The payload contains basic customer information.

Payload Structure

{
  "id": "string",           // The Vayu Id of the created customer
  "externalId": "string",   // The assumed external Id of the customer
  "aliases": "string[]",    // The aliases used to match events to this customer (will be the externalId for this event)
  "name": "string"          // The temporary assumed name of the customer
}

Example Payload

{
  "id": "cust_123456789",
  "externalId": "ext_987654321",
  "aliases": ["ext_987654321"],
  "name": "Anonymous Customer"
}

Webhook Security

For security purposes, all webhook requests include:

• A timestamp header (in seconds)
• A signature header (RSA-SHA256 signed message of ‘timestamp.payload’)
• The event type in the payload

Note: Only HTTPS endpoints are supported. HTTP endpoints are not allowed for security reasons.

Signature Verification:

To ensure the webhook is authentic, you must verify the webhook signature using the public key provided by Vayu.

Here’s a ready-to-use helper function you can drop into your backend codebase:

Typescript:

app.post('/webhooks', (req, res) => {
  const payload = JSON.stringify(req.body);
  const timestamp = Number(req.headers['x-timestamp']);
  const signature = String(req.headers['x-signature']);

  // Important to login before verifying webhook signatures.
  await vayu.login();
  
  const isValid = vayu.verifyWebhookSignature({
    payload,
    timestamp,
    signature,
  });

  if (!isValid) {
    // Handle invalid token.
  }

  // Proceed with webhook handling
  console.log('Webhook is valid', JSON.parse(payload));
  
  // ... Handle event.
  
  res.sendStatus(200);
});

Python:

Here’s a ready-to-use helper function you can drop into your backend codebase:

@app.route('/webhooks', methods=['POST'])
def webhooks():
    payload = request.get_data(as_text=True)
    timestamp = int(request.headers.get('X-Timestamp', '0'))
    signature = request.headers.get('X-Signature', '')
    
    # Important: authenticate with Vayu before verifying webhook signatures
    vayu.login()
    
    is_valid = vayu.verify_webhook_signature(
        payload=payload,
        timestamp=timestamp,
        signature=signature
    )
    
    if not is_valid:
        # Handle invalid token
    
    # Proceed with webhook handling
    print('Webhook is valid:', payload)

    # ... Handle event.
    
    return '', 200