openapi: 3.2.0
info:
  contact:
    email: support@gatiflow.io
    name: GatiFlow Support
    url: https://gatiflow.io/api-docs
  description: Customer-facing GatiFlow Intelligence API.
  license:
    name: Proprietary
    url: https://gatiflow.io/terms
  termsOfService: https://gatiflow.io/terms
  title: GatiFlow SaaS API — Public Webhooks API
  version: 2.3.0
servers:
- description: Production
  url: https://api.gatiflow.io
tags:
- name: Webhooks
paths: {}
webhooks:
  intelligence:alert:
    post:
      description: 'Sent to every active webhook of an organization on the Pro or Business plan when a collection cycle raises alerts that match its watchlist: a watched topic spiking or emerging, or a watched company appearing in the hiring feed for the first time. Alerts are raised while Signal Alerts is switched on in Settings, and one delivery carries every alert the cycle raised for the organization.


        Collection runs every six hours and delivery runs in the same cycle, right after the alerts are raised. A delivery that is not acknowledged is retried at each following cycle, up to five attempts, with the same X-GatiFlow-Delivery-Id; after the fifth failure the webhook is switched off and the organization owner is emailed. Ordering between deliveries is not guaranteed.


        Verify every request before acting on it: X-GatiFlow-Signature is t=,v1=, where is the HMAC-SHA256 of ''.'' under the secret shown once when the webhook was created. See https://gatiflow.io/api-docs/webhooks.'
      operationId: intelligenceAlert
      parameters:
      - description: The event type, the same value as event in the body.
        in: header
        name: X-GatiFlow-Event
        required: true
        schema:
          enum:
          - intelligence:alert
          type: string
      - description: t=<unix timestamp>,v1=<HMAC-SHA256 hex of '<timestamp>.<raw body>' under the webhook secret>. Compare in constant time and reject a mismatch.
        in: header
        name: X-GatiFlow-Signature
        required: true
        schema:
          pattern: ^t=[0-9]+,v1=[0-9a-f]{64}$
          type: string
      - description: The t= value of the signature, on its own. It is fixed when the event is raised and travels unchanged through every retry.
        in: header
        name: X-GatiFlow-Timestamp
        required: true
        schema:
          type: integer
      - description: One id per logical delivery, repeated on every retry. Use it to discard duplicates.
        in: header
        name: X-GatiFlow-Delivery-Id
        required: true
        schema:
          format: uuid
          type: string
      - description: Which attempt this is, 1 to 5.
        in: header
        name: X-GatiFlow-Attempt
        required: true
        schema:
          maximum: 5
          minimum: 1
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertEvent'
        required: true
      responses:
        2XX:
          description: Acknowledged. Any status below 400 within 10 seconds counts as delivered; redirects are not followed.
        default:
          description: A 4xx or 5xx, a timeout or a refused connection is a failed attempt and is retried.
      summary: Alerts raised for the organization's watchlist
      tags:
      - Webhooks
components:
  schemas:
    SpikeAlert:
      description: A watched topic grew past the spike threshold against its baseline.
      properties:
        change_pct:
          title: Change Pct
          type: number
        current_mentions:
          title: Current Mentions
          type: integer
        sources:
          description: Number of independent sources that observed it.
          title: Sources
          type: integer
        topic:
          title: Topic
          type: string
        type:
          const: spike
          title: Type
          type: string
      required:
      - type
      - topic
      - change_pct
      - current_mentions
      - sources
      title: SpikeAlert
      type: object
    AlertEvent:
      description: The body of every ``intelligence:alert`` delivery.
      properties:
        data:
          $ref: '#/components/schemas/AlertData'
        event:
          const: intelligence:alert
          title: Event
          type: string
      required:
      - event
      - data
      title: AlertEvent
      type: object
    NewHirerAlert:
      description: A watched company appeared in the hiring feed for the first time.
      properties:
        company:
          title: Company
          type: string
        source:
          title: Source
          type: string
        title:
          title: Title
          type: string
        type:
          const: new_hirer
          title: Type
          type: string
      required:
      - type
      - company
      - title
      - source
      title: NewHirerAlert
      type: object
    EmergingAlert:
      description: A watched topic appeared, with no baseline to compare against yet.
      properties:
        current_mentions:
          title: Current Mentions
          type: integer
        sources:
          description: Number of independent sources that observed it.
          title: Sources
          type: integer
        topic:
          title: Topic
          type: string
        type:
          const: emerging
          title: Type
          type: string
      required:
      - type
      - topic
      - current_mentions
      - sources
      title: EmergingAlert
      type: object
    AlertData:
      properties:
        alert_count:
          minimum: 1.0
          title: Alert Count
          type: integer
        alerts:
          items:
            discriminator:
              mapping:
                emerging: '#/components/schemas/EmergingAlert'
                new_hirer: '#/components/schemas/NewHirerAlert'
                spike: '#/components/schemas/SpikeAlert'
              propertyName: type
            oneOf:
            - $ref: '#/components/schemas/SpikeAlert'
            - $ref: '#/components/schemas/EmergingAlert'
            - $ref: '#/components/schemas/NewHirerAlert'
          title: Alerts
          type: array
        generated_at:
          format: date-time
          title: Generated At
          type: string
      required:
      - alert_count
      - alerts
      - generated_at
      title: AlertData
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: API key (prefix gf_) created in Dashboard → API Keys.
      in: header
      name: X-API-Key
      type: apiKey
    SessionBearer:
      bearerFormat: JWT
      description: Web session token issued to the browser at sign-in. It is not part of the public API and cannot be created from an API key; an API key sent to an operation that requires it receives 401.
      scheme: bearer
      type: http
externalDocs:
  description: API documentation
  url: https://gatiflow.io/api-docs
x-provenance:
  generated_from: the running routes (app/api/public_docs.py), compared byte for byte by the test suite
  method: published
  publisher: GatiFlow
  source: https://gatiflow.io/openapi.json