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

# Create a webhook

> Generates the signing secret and returns it once. Delivery: a bounded queue, three attempts over about five minutes, each recorded (GET /webhooks/{id}/deliveries). Body: WebhookEvent. Requires integrations:write.



## OpenAPI

````yaml /api-reference/openapi-public.json post /webhooks
openapi: 3.0.3
info:
  description: >-
    The API your own systems use: place and follow calls, have an AI agent call
    someone, run campaigns and get their results, keep contacts in step with
    your CRM, and receive signed webhooks. Authenticate with an integration key
    (Authorization: Bearer ft_...), used only from the IP addresses it allows.
  title: FireTone API
  version: 0.1.0
servers:
  - description: Your platform's API host
    url: https://{host}/api/v1
    variables:
      host:
        default: api.firet.one
security:
  - bearerAuth: []
tags:
  - name: Auth
  - description: >-
      Live calls and what can be done to them: hang up, hold, transfer, park,
      merge, monitor, whisper; the Desk's own call.
    name: Calls
  - description: 'Outbound campaigns: contacts, attempts, outcomes.'
    name: Campaigns
  - description: 'Customers: who called, what is known about them, and their memory.'
    name: Contacts
  - description: What was said on an AI call, and the review of it.
    name: Conversations
  - description: >-
      Your own systems: HTTP connections an IVR calls mid-call, and webhooks for
      call events. Tenant URLs must be public https addresses.
    name: Integrations
  - name: Live
  - name: Provisioning
  - name: Reporting
  - description: Tickets raised by people, agents and the API.
    name: Tickets
  - description: Messages left for an extension or a queue.
    name: Voicemail
paths:
  /webhooks:
    post:
      tags:
        - Integrations
      summary: Create a webhook
      description: >-
        Generates the signing secret and returns it once. Delivery: a bounded
        queue, three attempts over about five minutes, each recorded (GET
        /webhooks/{id}/deliveries). Body: WebhookEvent. Requires
        integrations:write.
      operationId: postWebhooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
          description: Created
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
components:
  schemas:
    WebhookCreate:
      properties:
        enabled:
          default: true
          type: boolean
        events:
          items:
            enum:
              - call.started
              - call.ringing
              - call.answered
              - call.ended
              - call.missed
              - voicemail.received
              - recording.ready
              - conversation.completed
              - callback.requested
              - ticket.created
              - ticket.updated
              - contact.created
              - campaign.contact.completed
              - campaign.completed
              - csat.submitted
            type: string
          type: array
        headers:
          additionalProperties:
            type: string
          type: object
        name:
          type: string
        organisation_id:
          format: uuid
          type: string
        url:
          description: https:// and a public address.
          type: string
      required:
        - name
        - url
        - events
      type: object
    Webhook:
      description: >-
        Call events posted to your URL. Every request carries
        X-FireTone-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "t.body")>,
        X-FireTone-Event and X-FireTone-Delivery. Header values and the secret
        are never returned.
      properties:
        created_at:
          format: date-time
          type: string
        disabled_reason:
          description: Why the webhook was switched off. Switching it back on clears it.
          nullable: true
          type: string
        enabled:
          type: boolean
        events:
          items:
            enum:
              - call.started
              - call.ringing
              - call.answered
              - call.ended
              - call.missed
              - voicemail.received
              - recording.ready
              - conversation.completed
              - callback.requested
              - ticket.created
              - ticket.updated
              - contact.created
              - campaign.contact.completed
              - campaign.completed
              - csat.submitted
            type: string
          type: array
        failing_since:
          description: >-
            Deliveries have failed without a success since then; three days of
            it switches the webhook off.
          format: date-time
          nullable: true
          type: string
        header_names:
          items:
            type: string
          type: array
        id:
          format: uuid
          type: string
        name:
          type: string
        organisation_id:
          format: uuid
          type: string
        secret:
          description: >-
            The signing secret. Only on the create and rotate responses: shown
            once.
          type: string
        updated_at:
          format: date-time
          type: string
        url:
          type: string
      type: object
    Error:
      properties:
        error:
          properties:
            code:
              enum:
                - invalid_request
                - invalid_credentials
                - unauthenticated
                - forbidden
                - not_found
                - conflict
                - internal
              type: string
            message:
              type: string
          required:
            - code
            - message
          type: object
      required:
        - error
      type: object
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: The request is not valid. The message names every field that is wrong.
    Conflict:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The row is still referenced, or a unique value is taken. The message
        names what still points at it.
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT or API key
      description: >-
        Every request sends `Authorization: Bearer <token>`. The token is either
        a panel session (a JWT from /auth/login, 12 hours) or an API key
        `ft_<id>_<secret>`. An API key is accepted only from an address on its
        IP allowlist (403 ip_not_allowed otherwise; 403 ip_allowlist_required
        for an old key that has none), is limited to its rate per minute (429
        rate_limited with Retry-After; X-RateLimit-Limit/Remaining/Reset on
        every response), and at most 60 call placements a minute.
      scheme: bearer
      type: http

````