Webhook Integration Guide

Gridio can notify your application in real time when events occur (e.g. a customer is created, a charging session starts). This guide explains how to set up an endpoint to receive webhooks and how to verify that incoming requests are authentic.

How It Works

  1. You register a webhook subscription through the Gridio API, providing a callback URL, a shared secret, and the event types you want to receive.
  2. When a matching event occurs, Gridio sends an HTTP POST request to your callback URL with a JSON payload describing the event.
  3. Your endpoint verifies the request signature, processes the event, and returns an HTTP 2xx response.

Setting Up Your Endpoint

Your webhook receiver must meet the following requirements:

Requirement Details
Protocol HTTPS (your callback URL must start with https://)
Method Accept POST requests
Content type Expect application/json body
Response Return any 2xx status code to acknowledge receipt
Timeout Respond promptly — long-running processing should be done asynchronously after acknowledging the webhook

Request Format

Headers

Every webhook request includes the following headers:

Header Example Description
Content-Type application/json Always JSON
X-Signature sha256=a1b2c3d4e5f6... HMAC-SHA256 signature of the request body
X-Request-ID 550e8400-e29b-41d4-a716-446655440000 Unique delivery ID — useful for deduplication and debugging
User-Agent Gridio-Webhook-Manager/v1.2.3 Identifies the Gridio webhook service

If required by your policy, you can add customer headers to webhooks. See create webhook (POST) and modify webhook (PATCH) requests.

Body

The JSON body has this structure:

{
  "event_type": "customer_create",
  "timestamp": "2026-02-06T12:34:56.789Z",
  "payload": {
    "customer_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}