> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gol.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Solana preview webhooks

> Explicit devnet subscriptions, raw-body HMAC verification, retries, and durable event deduplication.

Solana subscriptions are explicit and test-only. Default Base subscriptions do not include these events. Use preview SDK `.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.

```ts theme={null}
import { createSolanaApiClient } from "@gol/sdk/solana/server";
import { SOLANA_WEBHOOK_EVENT_TYPES } from "@gol/sdk/solana";

export async function subscribe() {
  const client = createSolanaApiClient({
    baseUrl: "https://api.gol.network",
    projectId: process.env.GOL_PROJECT_ID!, apiKey: process.env.GOL_TEST_API_KEY!,
  });
  const { endpoint, secret } = await client.createWebhookEndpoint({
    url: process.env.GOL_WEBHOOK_URL!,
    description: "Solana devnet preview",
    eventTypes: [...SOLANA_WEBHOOK_EVENT_TYPES],
  });
  // Store secret in your server secret store. It is shown once; never log it.
  return { endpointId: endpoint.id, secret };
}
```

| Event type | Finalized observation |
| - | - |
| `solana_mandate.created` | Mandate setup confirmed |
| `solana_mandate.state_changed` | Owner control confirmed, including grant/delegate or gas controls |
| `solana_mandate.closed` | Mandate closure confirmed |
| `solana_owner.invalidated` | Owner engine/authority epoch invalidation confirmed; `data.scope` is `engine` or `authority` |
| `solana_execution.executed` | Executed payment observed |
| `solana_execution.refused` | On-chain refusal observed |
| `solana_execution.settled` | Terminal execution observation, including paid, unpaid, or uncharged result |

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

Use `verifyWebhook` 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.

```ts theme={null}
import { verifyWebhook, GolWebhookVerificationError } from "@gol/sdk/server";
import { SOLANA_DEVNET_NETWORK, SOLANA_WEBHOOK_EVENT_TYPES } from "@gol/sdk/solana";

type EventData = { network: string; finality: string; [key: string]: unknown };
type PersistOnce = (eventId: string, event: unknown) => Promise<void>;

export function webhookReceiver(options: {
  projectId: string; secrets: readonly string[]; persistOnce: PersistOnce;
}) {
  return async function POST(request: Request): Promise<Response> {
    const raw = new Uint8Array(await request.arrayBuffer());
    try {
      const event = verifyWebhook<EventData>(raw, request.headers, options.secrets);
      if (event.projectId !== options.projectId || event.environment !== "test" ||
          !(SOLANA_WEBHOOK_EVENT_TYPES as readonly string[]).includes(event.type) ||
          event.data.network !== SOLANA_DEVNET_NETWORK || event.data.finality !== "finalized")
        return new Response(null, { status: 400 });
      // Atomic durable inbox insertion with a unique event ID.
      // Duplicates return success; queue/business work is committed atomically.
      await options.persistOnce(event.id, event);
      return new Response(null, { status: 204 });
    } catch (error) {
      return new Response(null, { status: error instanceof GolWebhookVerificationError ? 401 : 503 });
    }
  };
}
```

Implement `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](https://docs.gol.network/reference/overview.md) and `GolApiClient` 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](https://docs.gol.network/examples/solana/api-reference.md#createsolanawebhookendpoint) and [SDK reference](https://docs.gol.network/examples/solana/sdk-reference.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.