Environments

Environments let you separate your webhook infrastructure across development stages — like Production, Staging, and Development — within a single workspace. Each environment has its own API keys, endpoints, and event type visibility settings.

Why Environments?

Without environments, you'd need separate workspaces (or naming conventions) to keep production traffic away from test endpoints. Environments give you:

• Traffic isolation — an API key scoped to staging can only deliver to staging endpoints
• Event type gating — publish order.created to production without enabling it in staging
• Single workspace — manage everything in one place, with a quick environment switcher in the dashboard

Default Environment

Every workspace starts with a Production environment marked as the default. The default environment cannot be deleted.

When you create a new environment, existing event types are not automatically published to it — you control visibility per environment.

Creating Environments

Dashboard

Go to Settings > Environments and click Create Environment. Provide:

• Name — display name (e.g., "Staging")
• Slug — URL-safe identifier (e.g., staging). Must be lowercase alphanumeric with optional hyphens.

Management API

curl -X POST https://api.nahook.com/management/v1/workspaces/{workspaceId}/environments \
  -H "Authorization: Bearer nhm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Staging",
    "slug": "staging"
  }'

{
  "id": "env_abc123",
  "name": "Staging",
  "slug": "staging",
  "isDefault": false,
  "createdAt": "2026-04-04T10:00:00.000Z",
  "updatedAt": "2026-04-04T10:00:00.000Z"
}

How Environments Scope Resources

API Keys

Every API key belongs to exactly one environment. When you create an API key, you select which environment it targets.

Events ingested with a staging API key are only delivered to endpoints in the staging environment.

Endpoints

Every endpoint belongs to exactly one environment. When you create an endpoint, you select its environment.

Event Type Visibility

Event types are workspace-wide, but their visibility is controlled per environment. An event type must be published in an environment for fan-out delivery to work there.

For example, you might have order.created published in Production and Staging, but only publish order.refunded in Production until it's ready.

Event Type Visibility

Dashboard

Select an environment from the environment switcher, then go to Event Types. Toggle visibility on or off for each event type.

Management API

List event types with their visibility in an environment:

curl https://api.nahook.com/management/v1/workspaces/{workspaceId}/environments/{envId}/event-types \
  -H "Authorization: Bearer nhm_..."

[
  { "eventTypeId": "evt_abc", "eventTypeName": "order.created", "published": true },
  { "eventTypeId": "evt_def", "eventTypeName": "order.refunded", "published": false }
]

Toggle visibility:

curl -X PUT https://api.nahook.com/management/v1/workspaces/{workspaceId}/environments/{envId}/event-types/{eventTypeId}/visibility \
  -H "Authorization: Bearer nhm_..." \
  -H "Content-Type: application/json" \
  -d '{ "published": true }'

How Delivery Routing Works

When an event is ingested via fan-out (POST /api/ingest/event/:eventType):

1. The API key determines the environment
2. Nahook checks if the event type is published in that environment
3. Only endpoints in the same environment and subscribed to that event type receive deliveries

API Key (staging) → Event: order.created
                         │
                         ├── Published in staging? ✓
                         ├── Endpoint A (staging, subscribed) → Deliver ✓
                         ├── Endpoint B (production, subscribed) → Skip ✗
                         └── Endpoint C (staging, not subscribed) → Skip ✗

For direct delivery (POST /api/ingest/:endpointId), the endpoint must belong to the same environment as the API key.

Copying Environments

When creating a new environment, existing event type visibility settings are not copied. You'll need to publish the event types you want in the new environment individually.

Deleting Environments

Delete via dashboard (Settings > Environments) or via the Management API:

curl -X DELETE https://api.nahook.com/management/v1/workspaces/{workspaceId}/environments/{envId} \
  -H "Authorization: Bearer nhm_..."

Next Steps