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

# Create Webhook

> Register a URL to be told when the cases of a workspace change

Register an HTTPS URL that Penbox calls every time a case of the workspace changes.
Events, payload and signature are described in the [Webhooks guide](https://docs.penbox.io/api-reference/webhooks.md).

The response carries the `secret` that signs every call. Store it on your server; you can
read it again with [List Webhooks](https://docs.penbox.io/api-reference/webhooks/list-webhooks.md).

> [!NOTE]
>
> The URL must use `https`. `localhost`, `.local` hosts and private IP addresses (loopback,
> `10.x`, `172.16–31.x`, `192.168.x`, link-local, IPv6 unique-local) are refused with a `422`.
> A URL already registered on the workspace is refused with a `409`: register it once, not at
> each start of your app.

```bash All events theme={null}
curl --request POST \
  --url https://connect.penbox.io/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "workspace": { "id": "1ec1c284-4c03-445e-a843-c03058466f2a" },
    "url": "https://api.example.com/penbox/webhooks"
  }'
```

```bash Updates only theme={null}
curl --request POST \
  --url https://connect.penbox.io/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "workspace": { "id": "1ec1c284-4c03-445e-a843-c03058466f2a" },
    "url": "https://api.example.com/penbox/webhooks",
    "events": ["case.updated"]
  }'
```

```json 201 theme={null}
{
  "id": "8d0a3c2e-0d4b-4f1e-9a51-2b6c7d8e9f01",
  "created_at": "2026-10-24T13:00:00.000Z",
  "workspace": { "id": "1ec1c284-4c03-445e-a843-c03058466f2a" },
  "url": "https://api.example.com/penbox/webhooks",
  "events": ["case.created", "case.updated", "case.deleted"],
  "secret": "whsec_4f1c9a…"
}
```


## OpenAPI

````yaml POST /webhooks
openapi: 3.0.0
info:
  title: Penbox API
  version: '1.0'
  description: >-
    The Penbox API provides programmatic access to Penbox's form management,
    case management, and document processing capabilities. Authenticate using
    Bearer tokens created at https://app.penbox.io/workspace/settings/api
servers:
  - url: https://connect.penbox.io/v1
    description: Production
security:
  - BearerAuth: []
paths:
  /webhooks:
    post:
      summary: Create Webhook
      description: >-
        Register an HTTPS URL to be told when the cases of a workspace change.
        The response carries the signing secret.
      operationId: create-webhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - workspace
                - url
              properties:
                workspace:
                  type: object
                  required:
                    - id
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: The workspace whose cases to follow
                url:
                  type: string
                  format: uri
                  description: An HTTPS URL. `localhost` is refused.
                  example: https://api.example.com/penbox/webhooks
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - case.created
                      - case.updated
                      - case.deleted
                  minItems: 1
                  description: The events to receive. Defaults to all three.
      responses:
        '201':
          description: Endpoint registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          description: Invalid body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: This URL is already registered on this workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The URL is not HTTPS or points at localhost
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Endpoint ID
        created_at:
          type: string
          format: date-time
          description: When the endpoint was registered
        workspace:
          type: object
          description: The workspace whose cases this endpoint follows
          properties:
            id:
              type: string
              format: uuid
        url:
          type: string
          format: uri
          description: The HTTPS URL Penbox calls
        events:
          type: array
          items:
            type: string
            enum:
              - case.created
              - case.updated
              - case.deleted
          description: The events sent to this endpoint
        secret:
          type: string
          description: >-
            The secret that signs every call (`Penbox-Signature` header). Keep
            it on your server.
          example: whsec_4f1c…
      required:
        - id
        - workspace
        - url
        - events
        - secret
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: string
              title:
                type: string
              detail:
                type: string
              source:
                type: object
                properties:
                  pointer:
                    type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: >-
        API token (starts with pnbx_). Create at
        https://app.penbox.io/workspace/settings/api. Include as: Authorization:
        Bearer {token}

````

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