---
title: Create a webhook
description: Registers an HTTPS receiver for the events of the workspace, optionally only some event types and buckets.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Create a webhook

`POST /v1/workspaces/{workspaceId}/webhooks`

Registers an HTTPS receiver for the events of the workspace, optionally only some event types and buckets. Any member can make a personal webhook. A workspace key makes a workspace webhook. The signing secret appears once.

## Authentication

Send `Authorization: Bearer <GRAPHON_API_KEY>`. Read the key from the
GRAPHON_API_KEY environment variable. Never print it.

## Path parameters

- `workspaceId` (string) — The workspace id.

## Request body

- `name` (string) — Display name, 1 to 100 characters.
- `url` (string) — The receiver. HTTPS, no user name or password, no fragment, and a public address.
- `eventTypes` (string[] (optional)) — Event types to send. Leave out or send null for every type.
- `bucketIds` (string[] (optional)) — Buckets whose events to send. Leave out or send null for every bucket.
- `enabled` (boolean (optional)) — Default true.
- `owner` (string (optional)) — Defaults to me for a member and to workspace for a workspace key. Only an Admin can make a workspace webhook as a member. One of: me, workspace.

## Example request

```bash
curl \
  --url "https://api.beta.graphon.ai/v1/workspaces/wspq7ws2np5l8z4/webhooks" \
  --header "Authorization: Bearer $GRAPHON_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name":"indexing-callbacks","url":"https://hooks.example.com/graphon","eventTypes":["object.indexed","object.indexing_failed"]}'
```

## CLI

```bash
graphon webhooks create --name orders --url https://example.com/graphon --event-type object.indexed --write-env .env
```

## Example response

```json
{
  "webhook": {
    "id": "whkN4vB7qX2mZ",
    "workspaceId": "wspq7ws2np5l8z4",
    "name": "indexing-callbacks",
    "url": "https://hooks.example.com/graphon",
    "eventTypes": [
      "object.indexed",
      "object.indexing_failed"
    ],
    "bucketIds": null,
    "enabled": true,
    "disabledReason": null,
    "ownerKind": "user",
    "ownerUserId": "usrB2c3D4e5F6",
    "signing": {
      "secretFingerprint": "sha256:9b2d44f0",
      "previousSecretFingerprint": null,
      "previousSecretExpiresAt": null
    },
    "delivery": {
      "pendingDeliveries": 0,
      "lastSucceededAt": "2026-10-14T09:05:13.004Z",
      "lastFailedAt": null
    },
    "createdBy": {
      "userId": "usrB2c3D4e5F6",
      "apiKeyId": null
    },
    "createdAt": "2026-10-14T09:00:00.000Z",
    "updatedAt": "2026-10-14T09:00:00.000Z"
  },
  "secret": "whsec_<shown once>"
}
```

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.