openapi: 3.1.0
info:
  title: Bem Buckets Webhooks API
  version: 1.0.0
  description: "Buckets are named partitions of the knowledge graph within an\naccount+environment. Entities, mentions, and relations are scoped to a\nbucket so a single account+environment can host multiple isolated graphs\n— for example one per data source or workspace.\n\nEvery account+environment has exactly one **default** bucket, used by\nunscoped flows. The default bucket can be renamed but never deleted.\n\nUse these endpoints to create, list, fetch, rename, and delete buckets:\n\n- **`POST /v3/buckets`** creates a non-default bucket.\n- **`GET /v3/buckets`** lists buckets with cursor pagination\n  (`startingAfter` / `endingBefore` over `bucketID`).\n- **`PATCH /v3/buckets/{bucketID}`** updates `name` and/or `description`.\n- **`DELETE /v3/buckets/{bucketID}`** soft-deletes a bucket. A non-empty\n  bucket is rejected with `409 Conflict` unless `?cascade=true` is\n  passed; the default bucket can never be deleted."
servers:
- url: https://api.bem.ai
  description: US Region API
  variables: {}
- url: https://api.eu1.bem.ai
  description: EU Region API
  variables: {}
security:
- API Key: []
tags:
- name: Webhooks
  description: 'bem POSTs a JSON event to your configured webhook URL each time a subscribed function call, workflow output, or collection-processing job fires. This section is the reference for those deliveries: the payload shape per event type, plus the endpoints you use to manage the signing secret.


    Every variant shares the same envelope — function/workflow IDs, timestamps, the inbound email that triggered the call, and so on — and adds a payload field that depends on the function type. The `eventType` field on the body is the discriminator: dispatch on it to select which payload shape to expect. SDKs generated from this spec expose a `webhooks.unwrap()` helper that performs the dispatch and returns a typed event.


    ## Payloads


    | `eventType` | Payload | Schema |

    | --- | --- | --- |

    | `extract` | [Extract event](/api/v3/webhooks/events/extract) | `ExtractEvent` |

    | `classify` | [Classify event](/api/v3/webhooks/events/classify) | `ClassifyEvent` |

    | `parse` | [Parse event](/api/v3/webhooks/events/parse) | `ParseEvent` |

    | `split_collection` | [Split collection event](/api/v3/webhooks/events/split-collection) | `SplitCollectionEvent` |

    | `split_item` | [Split item event](/api/v3/webhooks/events/split-item) | `SplitItemEvent` |

    | `join` | [Join event](/api/v3/webhooks/events/join) | `JoinEvent` |

    | `enrich` | [Enrich event](/api/v3/webhooks/events/enrich) | `EnrichEvent` |

    | `payload_shaping` | [Payload shaping event](/api/v3/webhooks/events/payload-shaping) | `PayloadShapingEvent` |

    | `send` | [Send event](/api/v3/webhooks/events/send) | `SendEvent` |

    | `evaluation` | [Evaluation event](/api/v3/webhooks/events/evaluation) | `EvaluationEvent` |

    | `collection_processing` | [Collection processing event](/api/v3/webhooks/events/collection-processing) | `collectionProcessingEvent` |

    | `error` | [Error event](/api/v3/webhooks/events/error) | `ErrorEvent` |


    ## Signing secret


    Every delivery includes a `bem-signature` header in the format `t={unix_timestamp},v1={hex_hmac_sha256}`. The signature covers `{timestamp}.{raw_request_body}` and is computed with HMAC-SHA256 using the active signing secret for your environment.


    To verify a payload:


    1. Parse `bem-signature: t={timestamp},v1={signature}`.

    2. Construct the signed string: `{timestamp}.{raw_request_body}`.

    3. Compute HMAC-SHA256 of that string using your secret.

    4. Reject the request if the hex digest doesn''t match `v1`, or if the timestamp is more than a few minutes old.


    Manage the secret with these endpoints:


    - [**Generate a signing secret**](/api/v3/webhooks/secret/generate-secret) — `POST /v3/webhook-secret`. Returns the new secret in full exactly once.

    - [**Get the signing secret**](/api/v3/webhooks/secret/get-secret) — `GET /v3/webhook-secret`. Returns the active secret.

    - [**Revoke the signing secret**](/api/v3/webhooks/secret/revoke-secret) — `DELETE /v3/webhook-secret`. Webhook deliveries continue but are unsigned until a new secret is generated.


    For zero-downtime rotation, briefly accept both the old and new secret in your verification logic before revoking the old one.


    ## Retries


    bem treats any non-2XX response (or a transport failure) as a delivery error and retries with exponential backoff. Return a 2XX as soon as you have durably queued the payload — do not block on downstream work.'
paths:
  /v3/webhook-secret:
    get:
      operationId: v3-get-webhook-secret
      summary: Get Webhook Secret
      description: '**Get the current webhook signing secret.**


        Returns the active secret used to sign outbound webhook deliveries via the `bem-signature`

        header. Returns 404 if no secret has been generated for this environment yet.


        Use the secret to verify incoming webhook payloads:

        1. Parse `bem-signature: t={timestamp},v1={signature}`.

        2. Construct the signed string: `{timestamp}.{raw request body}`.

        3. Compute HMAC-SHA256 of that string using the secret.

        4. Compare the hex digest against `v1`.

        5. Reject requests where the timestamp is more than a few minutes old.'
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSecret'
      tags:
      - Webhooks
    post:
      operationId: v3-generate-webhook-secret
      summary: Generate Webhook Secret
      description: '**Generate a new webhook signing secret.**


        Creates a new signing secret for this environment (or replaces the existing one).

        The new secret is returned in full exactly once — store it securely.


        After rotation all newly delivered webhooks will be signed with the new secret.

        Update your verification logic before calling this endpoint if you need zero-downtime rotation.'
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSecret'
      tags:
      - Webhooks
    delete:
      operationId: v3-revoke-webhook-secret
      summary: Revoke Webhook Secret
      description: '**Revoke the current webhook signing secret.**


        Deletes the active signing secret. Webhook deliveries will continue but will no longer

        include a `bem-signature` header until a new secret is generated.'
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
      tags:
      - Webhooks
components:
  schemas:
    WebhookSecret:
      type: object
      required:
      - secret
      properties:
        secret:
          type: string
          description: The signing secret value. Store this securely — it is shown in full only on generation.
      description: Webhook signing secret used to verify `bem-signature` headers on delivered webhooks.
  securitySchemes:
    API Key:
      type: apiKey
      in: header
      name: x-api-key
      description: Authenticate using API Key in request header