Gate webhook

When a developer approves signup, Gate posts a gate.session.approved event to your webhook endpoint. Unlike other Foil webhooks, this one has a request/response contract: your handler must return an encrypted credentials envelope that the CLI decrypts and writes into the developer’s project. This page covers the Gate-specific bits. For everything common to all Foil webhooks - signature verification, retries, headers, the delivery log - see Webhooks.

Set up the endpoint

Create a webhook endpoint subscribed to gate.session.approved, then point your Gate service at it via webhook_endpoint_id. See Webhooks → Endpoints for both the dashboard flow and the API.

Verify the signature

Standard Foil HMAC verification - see Webhooks → Authentication for ready-to-paste code in Node.js, Python, Go, Ruby, and PHP.

Handle the payload

The envelope is the standard webhook envelope. The gate.session.approved data object is:

{
  "service_id": "foil",
  "gate_session_id": "gate_abc123...",
  "gate_account_id": "gacct_abc123...",
  "account_name": "my-project",
  "metadata": null,
  "delivery": {
    "version": 1,
    "algorithm": "x25519-hkdf-sha256/aes-256-gcm",
    "key_id": "<base64url sha256 of public_key>",
    "public_key": "<base64url raw X25519 public key>"
  },
  "foil": {
    "verdict": "human",
    "score": 0.12
  }
}

Field	Description
`service_id`	The registry service being provisioned. Use it if one webhook handles multiple services.
`gate_session_id`	Idempotency key. Use this to avoid creating duplicate accounts on retries.
`gate_account_id`	Stable identifier for this signup. Store it alongside your internal account.
`account_name`	The name the developer chose (defaults to their project directory name).
`metadata`	Optional key-value pairs the developer passed during signup.
`delivery`	CLI-provided encrypted delivery metadata. Encrypt your response outputs to this key.
`foil.verdict`	`human` or `inconclusive`. Bot verdicts are blocked before reaching your webhook.

The full schema is also published in the API reference under Webhooks.

Return credentials

Your webhook must return an encrypted delivery envelope, not raw keys or onboarding links. Gate owns the service metadata like docs_url; your webhook should only return the encrypted customer outputs.

{
  "encrypted_delivery": {
    "version": 1,
    "algorithm": "x25519-hkdf-sha256/aes-256-gcm",
    "key_id": "<same key_id>",
    "ephemeral_public_key": "<base64url raw X25519 public key>",
    "salt": "<base64url 32 bytes>",
    "iv": "<base64url 12 bytes>",
    "ciphertext": "<base64url>",
    "tag": "<base64url 16 bytes>"
  }
}

When decrypted by the CLI, the ciphertext should contain your registry-owned env_vars only, for example:

{
  "version": 1,
  "outputs": {
    "YOURPRODUCT_PUBLISHABLE_KEY": "pk_live_...",
    "YOURPRODUCT_SECRET_KEY": "sk_live_..."
  }
}

Idempotency

Gate may retry your webhook. Use gate_session_id to make requests idempotent:

// Check if we already processed this session
const existing = await db.findByGateSessionId(gate_session_id);
if (existing) return res.json(existing.credentials);

// First time - create the account
const account = await createAccount(account_name);
// ... save gate_session_id for future retries

The general retry rules - 5 attempts, ≥ 1 minute between attempts, dedupe by envelope id - apply here too. See Webhooks → Retries.

What’s next

Agent tokens - verify the tokens Gate issues
Dashboard login - let developers access your dashboard

Overview

Get started

Integrate Detection

Use cases

Learn

Gate: Agentic Signup

Integrate Gate

Resources

Gate webhook

Set up the endpoint

Verify the signature

Handle the payload

Return credentials

Idempotency

What’s next

​Set up the endpoint

​Verify the signature

​Handle the payload

​Return credentials

​Idempotency

​What’s next

Set up the endpoint

Verify the signature

Handle the payload

Return credentials

Idempotency

What’s next