Webhooks

Grid tells your backend about agent activity with the same signed webhooks it uses for everything else. Configure your endpoint in the dashboard, then handle the events below.

Agent events

Event	Sent when	Payload
`AGENT_ACTION.PENDING_APPROVAL`	An agent’s request needs the customer’s approval	The full `AgentAction`, including the quote, purchase card, stored card use, payout, payout run or settlement rule it is for
`AGENT_ACTION.APPROVED`	An action was approved, including a stored card use Grid auto-approved because the customer chose to	The `AgentAction`
`AGENT_ACTION.REJECTED`	An action was rejected	The `AgentAction`, with `rejectionReason` when one was given
`AGENT_ACTION.FAILED`	An action was not executed, or execution failed	The `AgentAction`, with `failureReason`
`CLAIMABLE_PAYOUT.CLAIMED`, `.PAID`, `.EXPIRED`, `.FAILED`	A claimable payout was claimed, paid, expired or failed. `EXPIRED` and `FAILED` mean the hold on the sender’s wallet was released	The `ClaimablePayout`
`PAYOUT_RUN.COMPLETED`, `.PARTIALLY_FAILED`, `.FAILED`	No row of a payout run is left to pay. A cancelled run sends none	The run with its row counts
`SETTLEMENT_RULE.EXECUTED`, `.FAILED`, `.SKIPPED`	A settlement rule’s execution on an incoming payment finished	The execution

The money itself moves with the standard INCOMING_PAYMENT and OUTGOING_PAYMENT webhooks, and agent cards send the same card status and card transaction webhooks as any card.

Pending approval example

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000021",
  "type": "AGENT_ACTION.PENDING_APPROVAL",
  "timestamp": "2026-10-26T15:00:00Z",
  "data": {
    "id": "AgentAction:019542f5-b3e7-1d02-0000-000000000098",
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
    "platformCustomerId": "user-a1b2c3",
    "status": "PENDING_APPROVAL",
    "type": "ISSUE_PURCHASE_CARD",
    "purchaseCard": {
      "amount": 12000,
      "spendLimit": 13000,
      "currency": "USD",
      "description": "Concert tickets from example-tickets.com",
      "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
    },
    "expiresAt": "2026-10-26T15:15:00Z",
    "createdAt": "2026-10-26T15:00:00Z",
    "updatedAt": "2026-10-26T15:00:00Z"
  }
}

Handling agent webhooks

Respond 200 quickly and do the work asynchronously. A webhook whose id you have already processed can be acknowledged and skipped.
On AGENT_ACTION.PENDING_APPROVAL, notify the customer immediately. A send without priceTolerance expires with its quote, often within minutes.
Don’t rely on webhooks alone for the approval queue. GET /agents/approvals rebuilds it if your endpoint was down.
Send a signed test event to your endpoint at any time with POST /webhooks/test.

All webhooks sent by the Grid API include a signature in the X-Grid-Signature header, which allows you to verify the authenticity of the webhook. This is critical for security, as it ensures that only legitimate webhooks from Grid are processed by your system.

Signature Verification Process

Obtain your Grid public key
- This is available in your dashboard under Developers webhook settings.
- The key is in PEM format and can be used with standard cryptographic libraries
Verify incoming webhooks
- Extract the signature from the X-Grid-Signature header
- Decode the base64 signature
- Create a SHA-256 hash of the entire request body
- Verify the signature using the Grid webhook public key and the hash
- Only process the webhook if the signature verification succeeds

Verification Examples

Node.js Example

const crypto = require('crypto');
const express = require('express');
const app = express();

// Your Grid public key provided during integration
const GRID_WEBHOOK_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
-----END PUBLIC KEY-----`;

app.post('/webhooks/uma', (req, res) => {
  const signatureHeader = req.header('X-Grid-Signature');

  if (!signatureHeader) {
    return res.status(401).json({ error: 'Signature missing' });
  }

  try {
    let signature: Buffer;
    try {
      // Parse the signature as JSON. It's in the format {"v": "1", "s": "base64_signature"}
      const signatureObj = JSON.parse(signatureHeader);
      if (signatureObj.v && signatureObj.s) {
        // The signature is in the 's' field
        signature = Buffer.from(signatureObj.s, "base64");
      } else {
        throw new Error("Invalid JSON signature format");
      }
    } catch {
      // If JSON parsing fails, treat as direct base64
      signature = Buffer.from(signatureHeader, "base64");
    }

    // Create verifier with the public key and correct algorithm
    const verifier = crypto.createVerify("SHA256");
    const payload = await request.text();
    verifier.update(payload);
    verifier.end();

    // Verify the signature using the webhook public key
    const isValid = verifier.verify(
      {
        key: GRID_WEBHOOK_PUBLIC_KEY,
        format: "pem",
        type: "spki",
      },
      signature,
    );

    if (!isValid) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    // Webhook is verified, process it based on type
    const webhookData = req.body;

    if (webhookData.type.startsWith('INCOMING_PAYMENT.')) {
      // Process incoming payment webhook
      // ...
    } else if (webhookData.type.startsWith('OUTGOING_PAYMENT.')) {
      // Process outgoing payment webhook
      // ...
    }

    // Acknowledge receipt of the webhook
    return res.status(200).json({ received: true });
  } catch (error) {
    console.error('Signature verification error:', error);
    return res.status(401).json({ error: 'Signature verification failed' });
  }
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Python Example

from cryptography.hazmat.primitives import serialization, hashes
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives.asymmetric.utils import decode_dss_signature
from flask import Flask, request, jsonify
import base64

app = Flask(__name__)

# Your Grid public key provided during integration
GRID_PUBLIC_KEY = """-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
-----END PUBLIC KEY-----"""

# Load the public key
public_key = serialization.load_pem_public_key(
    GRID_PUBLIC_KEY.encode('utf-8')
)

@app.route('/webhooks/uma', methods=['POST'])
def handle_webhook():
    # Get signature from header
    signature = request.headers.get('X-Grid-Signature')
    if not signature:
        return jsonify({'error': 'Signature missing'}), 401

    try:
        # Get the raw request body
        request_body = request.get_data()

        # Create a SHA-256 hash of the request body
        hash_obj = hashes.Hash(hashes.SHA256())
        hash_obj.update(request_body)
        digest = hash_obj.finalize()

        # Decode the base64 signature
        signature_bytes = base64.b64decode(signature)

        # Verify the signature
        try:
            public_key.verify(
                signature_bytes,
                request_body,
                ec.ECDSA(hashes.SHA256())
            )
        except Exception as e:
            return jsonify({'error': 'Invalid signature'}), 401

        # Webhook is verified, process it based on type
        webhook_data = request.json

        if webhook_data['type'].startswith('INCOMING_PAYMENT.'):
            # Process incoming payment webhook
            # ...
            pass
        elif webhook_data['type'].startswith('OUTGOING_PAYMENT.'):
            # Process outgoing payment webhook
            # ...
            pass

        # Acknowledge receipt of the webhook
        return jsonify({'received': True}), 200
    except Exception as e:
        print(f'Signature verification error: {e}')
        return jsonify({'error': 'Signature verification failed'}), 401

if __name__ == '__main__':
    app.run(port=3000)

Testing

To test your webhook implementation, you can trigger a test webhook from the Grid dashboard. This will send a test webhook to the endpoint you provided during the integration process. The test webhook will also be sent automatically when you update your platform configuration with a new webhook URL. An example of the test webhook payload is shown below:

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000007",
  "type": "TEST",
  "timestamp": "2025-08-15T14:32:00Z",
  "data": {}
}

You should verify the signature of the webhook using the Grid public key and the process outlined in the Signature Verification Process section and then reply with a 200 OK response to acknowledge receipt of the webhook.

Security Considerations

Always verify signatures: Never process webhooks without verifying their signatures.
Use HTTPS: Ensure your webhook endpoint uses HTTPS to prevent man-in-the-middle attacks.
Implement idempotency: Use the id field to prevent processing duplicate webhooks.
Timeout handling: Implement proper timeout handling and respond to webhooks promptly.

Retry Policy

The Grid API will retry webhooks with the following policy based on the webhook type:

Webhook Type	Retry Policy	Notes
`TEST`	No retries	Used for testing webhook configuration
`OUTGOING_PAYMENT.*`	Retry with exponential backoff up to 7 days with maximum interval of 30 mins	No retry on 409 (duplicate webhooks)
`INCOMING_PAYMENT.*`	Retry with exponential backoff up to 7 days with maximum interval of 30 mins	No retry on: 409 (duplicate webhook) or PENDING status since it is served as an approval mechanism in-flow
`BULK_UPLOAD.*`	Retry with exponential backoff up to 7 days with maximum interval of 30 mins	No retry on 409 (duplicate webhooks)
`WALLET_OPERATION.*`	Retry with exponential backoff up to 7 days with maximum interval of 30 mins	No retry on 409 (duplicate webhooks)
`INVITATION.*`	Retry with exponential backoff up to 7 days with maximum interval of 30 mins	No retry on 409 (duplicate webhooks)
`CUSTOMER.*`	Retry with exponential backoff up to 7 days with maximum interval of 30 mins	No retry on 409 (duplicate webhooks)
`ACCOUNT.*`	Retry with exponential backoff up to 7 days with maximum interval of 30 mins	No retry on 409 (duplicate webhooks)
`CARD.*`	Retry with exponential backoff up to 7 days with maximum interval of 30 mins	No retry on 409 (duplicate webhooks)
`CARD_TRANSACTION.*`	Retry with exponential backoff up to 7 days with maximum interval of 30 mins	No retry on 409 (duplicate webhooks)
`CARD_AUTHORIZATION.REQUEST`	No retries	Real-time decision request, sent only while `cardConfigs.realTimeAuthorization` is set

Overview

Add to your AI app

Build on the Agents API

Moving money

Platform tools

Agent events

Pending approval example

Handling agent webhooks

Signature Verification Process

Verification Examples

Node.js Example

Python Example

Testing

Security Considerations

Retry Policy

​Agent events

​Pending approval example

​Handling agent webhooks

​Signature Verification Process

​Verification Examples

​Node.js Example

​Python Example

​Testing

​Security Considerations

​Retry Policy

Agent events

Pending approval example

Handling agent webhooks

Signature Verification Process

Verification Examples

Node.js Example

Python Example

Testing

Security Considerations

Retry Policy