All documentation
Authentication

Webhooks: Headers and Security Checklist

Use PulseGrid's delivery headers safely and protect production receivers from forged requests and data leakage.

HTTP

Overview

Every PulseGrid webhook includes identifying and security headers. - X-PulseGrid-Delivery: unique delivery identifier used for idempotency. - X-PulseGrid-Endpoint: endpoint identifier in PulseGrid. - X-PulseGrid-Event: event name for quick routing and diagnostics. - X-PulseGrid-Timestamp: Unix timestamp included in the signature. - X-PulseGrid-Signature: versioned HMAC-SHA256 signature. - User-Agent: PulseGrid-Webhooks/1.0. The JSON body remains the source of truth for event content. Headers support verification and routing.

Setup

Production checklist: 1. Use HTTPS. 2. Keep the signing secret in environment variables or a secrets manager. 3. Verify signatures using the raw body. 4. Reject old timestamps. 5. Deduplicate delivery IDs. 6. Validate the payload before business processing. 7. Apply your own authorization rules after identifying project.id. 8. Limit request body size. 9. Avoid logging secrets or sensitive payloads. 10. Rotate the secret if exposed. 11. Monitor repeated failures. 12. Return a 2xx response only after the event is safely accepted.

Code example

Webhooks: Headers and Security Checklist 
X-PulseGrid-Delivery: afa3e157-1268-4ec0-977f-4556484722a0
X-PulseGrid-Endpoint: 67d37c12-35a3-4abb-9d2d-4b72bf4c7d0f
X-PulseGrid-Event: message
X-PulseGrid-Timestamp: 1787686820
X-PulseGrid-Signature: v1=1e70ad77061cc2cf249867f841c90069756b88f9fdd5832e591e4b2531cfb3d8
User-Agent: PulseGrid-Webhooks/1.0

Notes

Rotating a secret invalidates the old secret immediately. Update the receiving backend at the same time to prevent delivery failures. Pause an endpoint when maintaining its receiver. Resume it when the receiver is ready again.