.1, a test key with webhooks:manage, and the project-scoped Solana creation route. The receiver must be public HTTPS; localhost, private addresses, redirects and blocked destinations are refused.
Envelopes have
id, type, createdAt, projectId, environment: "test", and data. Data includes the devnet network and finality: "finalized"; payload fields vary by event. Polling remains authoritative. A settled event is not necessarily a successful payment. Validate event type, environment, project and network before handling it, then read the corresponding API resource as needed.
Verify the raw body before processing
UseverifyWebhook from the server entry point on the exact request bytes. It verifies HMAC SHA256 over timestamp.rawBody, the default 300-second timestamp tolerance, and the event ID’s match with gol-webhook-id. Headers are gol-webhook-id, gol-webhook-timestamp, and gol-webhook-signature (v1=<hex>, possibly multiple signatures during secret rotation). Do not parse and reserialize JSON before verifying.
persistOnce using durable storage with a unique event ID, not an in-memory set or a separate check-then-insert. Commit the inbox and queued work atomically before acknowledging. Repeated deliveries of the same event must return 2xx without repeating the business effect. Failed persistence returns non-2xx so delivery retries. Do not assume ordering across event types or treat notifications as authority to move funds.
Retries and management
Delivery is at least once. Any 2xx response succeeds; non-2xx, timeout or transport failure retries. After failed attempts the current schedule is 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 3 hours, 6 hours, and 12 hours; the ninth failed attempt abandons delivery. The event ID stays the same, while each retry has a fresh timestamp and signature. A receiver can see duplicates even after it returned 2xx. Return promptly after durable acceptance and do slow work asynchronously. Manage endpoints through the existing project webhook APIs: list, enable/disable, delete, rotate secret, send a test event, and inspect delivery history. Those APIs are covered by the existing API reference andGolApiClient from @gol/sdk/server; the test key selects the test environment. To change the event selection, create a new explicit subscription and disable/delete the old endpoint. A test delivery has type webhook.test, so handle it separately if enabled. Rotation overlaps the previous secret for 24 hours; pass current and previous server-held secrets during that window. Never publish either secret.
Hosted acceptance verified all seven types, invalid-HMAC rejection, a deliberately failed delivery’s successful retry with the same event ID, and receiver deduplication. This does not promise a fixed delivery latency. Recover abandoned/missing notifications through resource polling and delivery history. See the Solana API creation schema and SDK reference.