Webhook Signatures — Proposed Guide

Planned API — Reference Only

Webhook Signatures: A signature design would authenticate the exact payload bytes and a freshness value. Parsing and reserializing JSON before…

Overview

A signature design would authenticate the exact payload bytes and a freshness value. Parsing and reserializing JSON before verification can change the signed representation.

Key concepts

Verify the raw body, signature and timestamp before processing. Compare signatures using a suitable constant-time primitive in a future receiver.

Implementation considerations

The fixture does not contain a real signature. No algorithm, replay window or published signing contract is guaranteed.

Illustrative data model

This local fixture shows a possible representation for the concepts above. It is not an endpoint response, production configuration or a claim that the described capability is implemented.

JSON fixture

Fictional concept fixture

{
  "reference_only": true,
  "topic": "Webhook Signatures",
  "event_id": "event_example_123",
  "key_id": "key_example_123",
  "signature": "SIGNATURE_PLACEHOLDER",
  "timestamp": "2026-01-15T12:00:00Z"
}

Design review checklist

Document which organization owns the webhook signatures representation and which actor may view or change it.
Test the boundaries of event id, key id, signature, timestamp using synthetic values, including missing or inconsistent references.
Before future implementation, obtain an approved contract and review failure behavior. This documentation does not authorize production activation.

Proposed data types

Illustrative field dictionary
Name	Type	Description
event_id	string	Stable fictional event reference; not a secret and not evidence that a resource exists.
key_id	string	Stable fictional key reference; not a secret and not evidence that a resource exists.
signature	string	Non-operational placeholder; no secret, digest or verified signature is supplied.
timestamp	string (date-time)	Synthetic UTC timestamp. Business occurrence time may differ from delivery or processing time.

Webhook Authentication

Webhooks & Events

Webhook Security