Build Your Own Contextual Access Server

This guide walks through implementing a webhook server that satisfies the Contextual Access Webhook contract. You can write it in any language — the contract is defined by an OpenAPI 3.0 spec.

OpenAPI spec

The canonical contract is maintained in the ArcadeAI/schemas  repository:

• OpenAPI 3.0 spec: logic_extensions/http/1.0/schema.yaml 

You can browse it interactively on the API Reference page.

Generate server stubs

Use the OpenAPI spec with standard code generators to scaffold your server:

Example (Go with oapi-codegen):

curl -sL https://raw.githubusercontent.com/ArcadeAI/schemas/main/logic_extensions/http/1.0/schema.yaml -o schema.yaml
oapi-codegen -generate types,server -package server schema.yaml

The logic-extensions-examples  repo uses this approach — see pkg/server/ for the generated types.

Endpoints to implement

Your server needs to expose HTTP POST endpoints for each hook point you want to handle. Endpoint paths are fully configurable in the Dashboard — the defaults are shown below.

You do not need to implement all endpoints. Only implement the ones you configure in the Dashboard.

Pre-Execution Hook

When: Before each tool execution.

Request (Arcade sends to your server)

Response (your server returns)

Post-Execution Hook

When: After tool execution.

Request

Response

Access Hook

When: When Arcade needs to know which tools a user can see. Supports batch requests.

Request

Response

Return either an allow list or a deny list (not both):

If you return neither field, the Arcade treats it as “no change”—all tools remain allowed at this hook.

Tool Metadata

Tools can include an optional metadata field with classification, behavioral, and custom information. Webhook servers can use this metadata to make more granular access and filtering decisions.

All metadata fields are optional and omitted from the JSON when empty, so existing webhook servers continue to work without changes.

For the full list of valid service_domains and operations values, see Add Tool Metadata.

Structure

Example: pre/post hook request with metadata

{
  "execution_id": "exec_abc123",
  "tool": {
    "name": "ListEmails",
    "toolkit": "Gmail",
    "version": "1.0.0",
    "metadata": {
      "classification": {
        "service_domains": ["email"]
      },
      "behavior": {
        "operations": ["read"],
        "read_only": true,
        "destructive": false,
        "idempotent": true,
        "open_world": false
      },
      "extras": {
        "IdP": "entra_id"
      }
    }
  },
  "inputs": { "query": "from:boss@company.com" },
  "context": { "user_id": "user_123" }
}

Example: access hook request with metadata

{
  "user_id": "user_123",
  "toolkits": {
    "Gmail": {
      "tools": {
        "ListEmails": [
          {
            "version": "1.0.0",
            "metadata": {
              "classification": {
                "service_domains": ["email"]
              },
              "behavior": {
                "operations": ["read"],
                "read_only": true
              }
            },
            "requirements": {
              "authorization": [{ "provider_type": "oauth2" }]
            }
          }
        ]
      }
    }
  }
}

Use cases

Webhook servers can use tool metadata to make more granular decisions:

• Block destructive operations—Deny tools where metadata.behavior.destructive is true for certain users
• Restrict by service domain—Only allow tools in the "email" domain for a particular project
• Audit read vs. write—Log or rate-limit tools based on their operations array
• Route by IdP—Use metadata.extras.IdP to apply provider-specific policies

Response codes (pre and post)

Authentication

Arcade sends one of:

• Bearer: Authorization: Bearer <token> (token from extension config)
• mTLS: Client certificate during TLS handshake; optional CA cert for server verification

Configure the auth method when creating your extension in the Dashboard.

Failure handling and retries

• Timeout: Configurable per extension (default 5s); can be overridden per hook. On timeout, the hook’s failure mode applies (Fail closed = block, Fail open = allow).
• Retries: Optional at the extension level; only for transient failures (5xx, timeout, connection error). 4xx responses are not retried.

Next steps

• API Reference — Interactive Swagger documentation for the full schema
• Run an extension — Try the open-source example servers as reference
• How Hooks Work — Understand execution order, phases, and failure modes