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

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"
  }
}
Field Type Description
event_type string The type of event that occurred (see table below)
timestamp string (ISO 8601) When the event was generated
payload object Event-specific data containing the relevant resource ID