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

# Configure project webhook

> Create or replace the project webhook for the project behind the API key, and activate it. The response carries the signing `secret`; an existing secret is kept.

This is where `invitation.status_changed` is delivered. Events are scoped to this project: when you onboard clients in sub-accounts, call this with each sub-account's API key.



## OpenAPI

````yaml /openapi.json post /v1/invitations/webhook
openapi: 3.0.3
info:
  title: Zavu Unified Messaging Layer API
  version: 0.2.0
  description: >
    Unified multi-channel messaging API for Zavu.


    Supported channels:

    - **SMS**: Simple text messages

    - **WhatsApp**: Rich messaging with media, buttons, lists, CTA URL buttons,
    location requests, and templates

    - **Telegram**: Bot messaging with text, media, and interactive elements

    - **Email**: Transactional emails via Amazon SES


    Design goals:

    - Simple `send()` entrypoint for developers

    - Project-level authentication via Bearer token

    - Support for all WhatsApp message types (text, image, video, audio,
    document, sticker, location, contact, buttons, list, cta_url,
    location_request, reaction, template)

    - If a non-text message type is sent, WhatsApp channel is used automatically

    - 24-hour WhatsApp conversation window enforcement

    - Universal `to` field accepts phone numbers (E.164), email addresses, or
    numeric chat IDs (Telegram/Instagram/Messenger)
servers:
  - url: https://api.zavu.dev
security:
  - bearerAuth: []
paths:
  /v1/invitations/webhook:
    post:
      summary: Configure project webhook
      description: >-
        Create or replace the project webhook for the project behind the API
        key, and activate it. The response carries the signing `secret`; an
        existing secret is kept.


        This is where `invitation.status_changed` is delivered. Events are
        scoped to this project: when you onboard clients in sub-accounts, call
        this with each sub-account's API key.
      operationId: configureProjectWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectWebhookCreateRequest'
      responses:
        '201':
          description: Webhook configured.
          content:
            application/json:
              schema:
                type: object
                required:
                  - webhook
                properties:
                  webhook:
                    $ref: '#/components/schemas/ProjectWebhook'
        '400':
          description: Invalid URL or an event a project webhook cannot subscribe to.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    ProjectWebhookCreateRequest:
      type: object
      required:
        - url
        - events
      properties:
        url:
          type: string
          format: uri
          example: https://your-app.com/webhooks/zavu
        events:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ProjectWebhookEvent'
          example:
            - invitation.status_changed
    ProjectWebhook:
      type: object
      description: >-
        The project-level webhook. It receives project events such as
        `invitation.status_changed` for this project only: a parent project does
        not receive its sub-accounts' events, so configure one per sub-account
        with that sub-account's API key.
      required:
        - url
        - events
        - active
      properties:
        url:
          type: string
          format: uri
          example: https://your-app.com/webhooks/zavu
        events:
          type: array
          items:
            $ref: '#/components/schemas/ProjectWebhookEvent'
        secret:
          type: string
          description: >-
            Signing secret for `X-Zavu-Signature`. Returned only by `POST
            /v1/invitations/webhook`.
          example: whsec_abc123...
        active:
          type: boolean
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: invalid_request
        message:
          type: string
          example: Phone number is invalid
        details:
          type: object
          additionalProperties: true
    ProjectWebhookEvent:
      type: string
      description: >-
        Events a project webhook can subscribe to. Any other value is refused
        with `400`.
      enum:
        - invitation.status_changed
        - broadcast.status_changed
        - domain.verified
        - domain.failed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````