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/
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/
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/flyitalyadsb:flyitalyadsb-webhooks-api"
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.
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: 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/