FlyItalyADSB Webhooks API

Signed push alerts on the same events, paid plans only; on Fleet also the takeoffs and landings of the watched aircraft. https://flyitalyadsb.com/data/api/docs/alerts/

GitHub OpenAPI

Operations 6

GET /v2/webhooks The account's webhooks #
POST /v2/webhooks Create a webhook #
GET /v2/webhooks/{id}/deliveries A webhook's last 20 deliveries #
POST /v2/webhooks/{id}/delete Delete a webhook #
POST /v2/webhooks/{id}/enable Enable a webhook again after it was disabled #
POST /v2/webhooks/{id}/test Send a test delivery #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/flyitalyadsb:flyitalyadsb-webhooks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

flyitalyadsb-webhooks-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: FlyItalyADSB Webhooks API
  version: '2'
  summary: Live and historical aircraft positions worldwide from the FlyItalyADSB community ADS-B/MLAT network. Commercial use allowed on every plan, Free included; the whole world in one request from the Pro plan (€49/month).
  description: 'Unfiltered aircraft data (no FAA/LADD/BARR filtering; military aircraft included, many of them via MLAT) from a global network of receivers run by volunteers (about 3,200 receivers, densest in North America and Europe; any point on Earth can be queried), as readsb aircraft.json records (the same format as tar1090), plus an ADS-B Exchange v2–compatible variant at /api/aircraft/v2. PIA and LADD aircraft are flagged in the dbFlags bit field (value 4 for PIA, 8 for LADD), so your product can hide them where its market or app store requires. Every endpoint except the key signup needs an X-Api-Key; keys are self-serve (see /auth.md). Plans and limits: https://flyitalyadsb.com/data/api/#piani. The same key works on the MCP server at https://flyitalyadsb.com/mcp. The same data is also served in the ADS-B Exchange v2 format (same paths, key headers and JSON; radius in nautical miles) at https://api.flyitalyadsb.com/api/aircraft/v2, documented at https://flyitalyadsb.com/data/api/docs/adsbx-v2/. Operated by Nesso Labs S.r.l. (ISO/IEC 27001:2022, QMSCERT 160426-7).'
  termsOfService: https://flyitalyadsb.com/terms/
  contact:
    name: Nesso Labs S.r.l. (FlyItalyADSB)
    email: info@flyitalyadsb.com
    url: https://flyitalyadsb.com/contact/
  license:
    name: 'Data: CC BY-SA 4.0'
    url: https://creativecommons.org/licenses/by-sa/4.0/
servers:
- url: https://api.flyitalyadsb.com
security:
- ApiKey: []
tags:
- name: Webhooks
  description: Signed push alerts on the same events, paid plans only; on Fleet also the takeoffs and landings of the watched aircraft. https://flyitalyadsb.com/data/api/docs/alerts/
paths:
  /v2/webhooks:
    get:
      summary: The account's webhooks
      description: Never includes the signing secret. Not counted as a request (at most 20 webhook calls a minute per key).
      tags:
      - Webhooks
      responses:
        '200':
          description: The webhooks, and the maximum per account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: Database unavailable, try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV2Webhooks
      x-operation-id-source: derived
    post:
      summary: Create a webhook
      description: 'Paid plans only, at most 5 per account. The URL must be https on port 443 or 8443 and resolve only to public addresses. The answer carries the signing secret, shown this once. An area webhook has lat, lon and dist (capped by the plan''s radius) and area kinds. A webhook for the watched aircraft (Fleet) has kinds takeoff and/or landing and no area: it receives flight.takeoff, flight.landing and flight.landing_retracted for every aircraft in /v2/watch. https://flyitalyadsb.com/data/api/docs/alerts/#aircraft'
      tags:
      - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - title: Area webhook
                type: object
                required:
                - url
                - lat
                - lon
                - dist
                properties:
                  url:
                    type: string
                    format: uri
                    maxLength: 500
                  lat:
                    type: number
                    minimum: -90
                    maximum: 90
                  lon:
                    type: number
                    minimum: -180
                    maximum: 180
                  dist:
                    type: number
                    exclusiveMinimum: 0
                    maximum: 20040
                    description: Radius in km.
                  kinds:
                    type: array
                    items:
                      enum:
                      - emergency
                      - military
                      - interesting
                    description: Default ["emergency", "military"].
                  description:
                    type: string
                    maxLength: 200
              - title: Watched aircraft webhook
                type: object
                required:
                - url
                - kinds
                properties:
                  url:
                    type: string
                    format: uri
                    maxLength: 500
                  kinds:
                    type: array
                    minItems: 1
                    items:
                      enum:
                      - takeoff
                      - landing
                    description: No lat, lon or dist (400 with an area); not mixed with area kinds (400).
                  landings:
                    type: string
                    enum:
                    - confirmed
                    - fast
                    default: confirmed
                    description: 'Landings deduced from the aircraft disappearing low near a field: confirmed waits 4 minutes and sends them only if the aircraft was not seen flying again (about 5% withdrawn later), fast sends them at once (about 17% withdrawn). Takeoffs and landings seen on the ground are sent at once either way.'
                  description:
                    type: string
                    maxLength: 200
      responses:
        '201':
          description: Created; store the secret now.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCreated'
        '400':
          description: Invalid JSON, url not allowed (code "url-not-allowed"), an area or kind out of range, an area on a takeoff/landing webhook, or takeoff/landing mixed with area kinds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Webhooks are for paid plans (code "paid-plan-required"); takeoff and landing webhooks are for the plan with watched aircraft, Fleet (code "watch-plan-required").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The account already has the maximum number of webhooks (code "webhook-limit").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: Database unavailable, try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postV2Webhooks
      x-operation-id-source: derived
  /v2/webhooks/{id}/deliveries:
    get:
      summary: A webhook's last 20 deliveries
      tags:
      - Webhooks
      parameters:
      - name: id
        in: path
        required: true
        description: Webhook id.
        schema:
          type: integer
      responses:
        '200':
          description: Newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No webhook with this id for this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: Database unavailable, try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV2WebhooksByIdDeliveries
      x-operation-id-source: derived
  /v2/webhooks/{id}/delete:
    post:
      summary: Delete a webhook
      description: Allowed on any plan. Pending deliveries are cancelled.
      tags:
      - Webhooks
      parameters:
      - name: id
        in: path
        required: true
        description: Webhook id.
        schema:
          type: integer
      responses:
        '200':
          description: 'Deleted ({"status": "ok"}).'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No webhook with this id for this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: Database unavailable, try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postV2WebhooksByIdDelete
      x-operation-id-source: derived
  /v2/webhooks/{id}/enable:
    post:
      summary: Enable a webhook again after it was disabled
      description: A webhook is disabled after 15 failed attempts in a row over at least an hour. This resets the count.
      tags:
      - Webhooks
      parameters:
      - name: id
        in: path
        required: true
        description: Webhook id.
        schema:
          type: integer
      responses:
        '200':
          description: Enabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Webhooks are for paid plans (code "paid-plan-required").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No webhook with this id for this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: Database unavailable, try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postV2WebhooksByIdEnable
      x-operation-id-source: derived
  /v2/webhooks/{id}/test:
    post:
      summary: Send a test delivery
      description: Queues one `webhook.test` delivery, signed like the others, attempted once. See its outcome in /deliveries.
      tags:
      - Webhooks
      parameters:
      - name: id
        in: path
        required: true
        description: Webhook id.
        schema:
          type: integer
      responses:
        '202':
          description: Queued ({"delivery_id", "message"}).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Webhooks are for paid plans (code "paid-plan-required").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No webhook with this id for this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'The webhook is disabled (code "disabled"): enable it first.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: Database unavailable, try again shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postV2WebhooksByIdTest
      x-operation-id-source: derived
webhooks:
  trafficEvent:
    post:
      summary: A notable-traffic event, sent to your webhook URL
      description: 'Signed with Standard Webhooks (https://www.standardwebhooks.com/): HMAC-SHA256 with the base64-decoded part of the secret after "whsec_", over "{webhook-id}.{webhook-timestamp}.{raw body}". Reject a timestamp more than 5 minutes away and dedupe on webhook-id, which is the same on every retry. Answer 2xx within 10 seconds; anything else (redirects included) is retried 6 times over about 5 hours. https://flyitalyadsb.com/data/api/docs/alerts/'
      tags:
      - Webhooks
      security: []
      parameters:
      - name: webhook-id
        in: header
        required: true
        description: msg_<delivery id>, the same on every retry.
        schema:
          type: string
      - name: webhook-timestamp
        in: header
        required: true
        description: Unix seconds of this attempt.
        schema:
          type: string
      - name: webhook-signature
        in: header
        required: true
        description: '"v1,<base64 signature>".'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPayload'
      responses:
        '200':
          description: 'Any 2xx: delivered.'
  flightAlert:
    post:
      summary: A takeoff or landing of a watched aircraft, sent to a takeoff/landing webhook…
      description: 'Signed and retried like trafficEvent. Detected in real time from the network''s receivers, best effort: a takeoff or landing the network does not see is not sent. One alert per aircraft and kind every 20 minutes (circuits). A landing deduced from the aircraft disappearing near a field comes about 2.5 minutes after its last signal; if the aircraft is seen flying again within 10 minutes, flight.landing_retracted follows (same event_id), only to the webhooks that got the landing. Events detected more than 15 minutes earlier are never sent. https://flyitalyadsb.com/data/api/docs/alerts/#aircraft'
      tags:
      - Webhooks
      security: []
      parameters:
      - name: webhook-id
        in: header
        required: true
        description: msg_<delivery id>, the same on every retry.
        schema:
          type: string
      - name: webhook-timestamp
        in: header
        required: true
        description: Unix seconds of this attempt.
        schema:
          type: string
      - name: webhook-signature
        in: header
        required: true
        description: '"v1,<base64 signature>".'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/FlightAlertPayload'
              - $ref: '#/components/schemas/FlightRetractPayload'
      responses:
        '200':
          description: 'Any 2xx: delivered.'
components:
  schemas:
    FlightAlertPayload:
      type: object
      required:
      - type
      - timestamp
      - data
      properties:
        type:
          enum:
          - flight.takeoff
          - flight.landing
        timestamp:
          type: string
          format: date-time
          description: detected_at.
        data:
          type: object
          properties:
            webhook_id:
              type: integer
            event_id:
              type: integer
            kind:
              enum:
              - takeoff
              - landing
            time:
              type: string
              format: date-time
              description: When it happened; for a landing deduced from the aircraft disappearing, its last signal.
            detected_at:
              type: string
              format: date-time
            aircraft:
              $ref: '#/components/schemas/FlightAlertAircraft'
            airport:
              type: string
              description: ICAO code where there is one, otherwise the OurAirports code.
            place:
              enum:
              - airport
              - heliport
            distance_km:
              type:
              - number
              - 'null'
            near:
              type: boolean
              description: 'true beyond 2 km: "near" the airport, not "at".'
            seen:
              enum:
              - ground
              - low
              - approach
            runway:
              type:
              - string
              - 'null'
            position:
              type: object
              properties:
                lat:
                  type: number
                lon:
                  type: number
                alt_ft:
                  type:
                  - integer
                  - 'null'
                gs_kt:
                  type:
                  - number
                  - 'null'
                track:
                  type:
                  - number
                  - 'null'
            watch:
              type: object
              description: The entry of the list that matched.
              properties:
                kind:
                  type: string
                value:
                  type: string
                label:
                  type:
                  - string
                  - 'null'
            map:
              type: string
              format: uri
    WebhookList:
      type: object
      properties:
        webhooks:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
        max:
          type: integer
    Webhook:
      type: object
      properties:
        id:
          type: integer
        for:
          enum:
          - area
          - aircraft
          description: 'aircraft: a takeoff and landing webhook for the watched aircraft, with no area.'
        url:
          type: string
        lat:
          type:
          - number
          - 'null'
        lon:
          type:
          - number
          - 'null'
        dist:
          type:
          - number
          - 'null'
        kinds:
          type: array
          items:
            type: string
        description:
          type:
          - string
          - 'null'
        status:
          enum:
          - active
          - disabled
          - paused-plan
          description: 'paused-plan: the account has no paid key now.'
        created_at:
          type: string
          format: date-time
        disabled_at:
          type:
          - string
          - 'null'
          format: date-time
        disabled_reason:
          type:
          - string
          - 'null'
        consecutive_failures:
          type: integer
        last_success_at:
          type:
          - string
          - 'null'
          format: date-time
        last_failure_at:
          type:
          - string
          - 'null'
          format: date-time
        pending_deliveries:
          type: integer
    WebhookPayload:
      type: object
      required:
      - type
      - timestamp
      - data
      properties:
        type:
          enum:
          - event.emergency
          - event.military
          - event.interesting
          - webhook.test
        timestamp:
          type: string
          format: date-time
        data:
          description: The event (TrafficEvent, with webhook_id and distance_km from the webhook centre), or {webhook_id, message} for a test.
          $ref: '#/components/schemas/TrafficEvent'
    WebhookResult:
      type: object
      properties:
        webhook:
          $ref: '#/components/schemas/Webhook'
    TrafficEvent:
      type: object
      description: An event, plus the aircraft fields known at that moment with readsb's names (flight, r, t, desc, year, alt_baro, gs, track, squawk, emergency, category, dbFlags); `source` is readsb's position type. Never the owner or operator.
      required:
      - id
      - kind
      - hex
      - time
      - lat
      - lon
      properties:
        id:
          type: integer
        kind:
          enum:
          - emergency
          - military
          - interesting
        reason:
          enum:
          - general
          - hijack
          - radio_failure
          - minimum_fuel
          - downed
          description: Emergencies only.
        hex:
          type: string
        time:
          type: string
          format: date-time
          description: When the aircraft was seen entering the cell.
        lat:
          type: number
        lon:
          type: number
        distance_km:
          type: number
          description: From the query point (or the webhook centre).
        source:
          type: string
          description: adsb_icao, mlat, …
        map:
          type: string
          format: uri
          description: The aircraft on the live map.
      additionalProperties: true
    FlightRetractPayload:
      type: object
      required:
      - type
      - timestamp
      - data
      properties:
        type:
          const: flight.landing_retracted
        timestamp:
          type: string
          format: date-time
          description: retracted_at.
        data:
          type: object
          properties:
            webhook_id:
              type: integer
            event_id:
              type: integer
              description: The event_id of the flight.landing it withdraws.
            kind:
              const: landing
            time:
              type: string
              format: date-time
            retracted_at:
              type: string
              format: date-time
            reason:
              type: string
              description: 'reappeared: the aircraft was seen flying again.'
            aircraft:
              $ref: '#/components/schemas/FlightAlertAircraft'
            airport:
              type: string
            message:
              type: string
    FlightAlertAircraft:
      type: object
      properties:
        icao:
          type: string
        registration:
          type:
          - string
          - 'null'
        callsign:
          type:
          - string
          - 'null'
        type:
          type:
          - string
          - 'null'
          description: ICAO type designator.
        helicopter:
          type: boolean
    WebhookCreated:
      type: object
      properties:
        webhook:
          $ref: '#/components/schemas/Webhook'
        secret:
          type: string
          description: whsec_…, shown only in this answer.
        message:
          type: string
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        code:
          type: string
        help:
          type: string
          format: uri
          description: 'On 401, 403 and 429: the FAQ answer for this error.'
      additionalProperties: true
    DeliveryList:
      type: object
      properties:
        deliveries:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              type:
                type: string
                description: event.emergency, event.military, event.interesting, flight.takeoff, flight.landing, flight.landing_retracted, webhook.test
              event_id:
                type:
                - integer
                - 'null'
              status:
                enum:
                - pending
                - sending
                - delivered
                - failed
                - expired
                - dropped
                - cancelled
              attempts:
                type: integer
              created_at:
                type: string
                format: date-time
              next_attempt_at:
                type: string
                format: date-time
              delivered_at:
                type:
                - string
                - 'null'
                format: date-time
              last_status:
                type:
                - integer
                - 'null'
                description: HTTP status of the last attempt.
              last_error:
                type:
                - string
                - 'null'
              last_duration_ms:
                type:
                - integer
                - 'null'
  responses:
    TooManyRequests:
      description: Per-minute limit (key or, on Free, IP) or the plan's monthly quota. Per-minute answers carry Retry-After.
      headers:
        Retry-After:
          description: Seconds to wait.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid X-Api-Key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: 'Self-serve: https://flyitalyadsb.com/data/api/#api-key'
externalDocs:
  description: 'API page: plans, endpoints, free key'
  url: https://flyitalyadsb.com/data/api/