NOTAM Watcher API

The Notamify Watcher Service allows automatic retrieval of new interpretations in Notamify based on configurable filters. The service supports listener management via webhooks, enabling applications to subscribe to NOTAM updates by airport code, category, subcategory, or specific NOTAM identifiers.

The Watcher service charges credits based on the number of NOTAM deliveries sent to registered listeners:

Default: 1 credit = 5 shipments — 1 credit is deducted for every 5 NOTAMs shipped to your listeners.
An account-specific shipments-per-credit allowance may override the default rate.
Lifecycle messages are not chargeable.
If the user has no credits remaining, further shipments are blocked until credits are topped up.

An account can have up to 15 listeners.

If you specified webhook_url the service will provide each new notam for the filter as described in Watcher API Webhook messages.

Watcher API expects to receive a 2xx success response, such as 200, after delivering a webhook message. 25 consecutive failed deliveries will pause the listener by setting active: false.

Python SDK Example

The Notamify Python SDK provides typed methods for all Watcher operations:

from notamify_sdk import NotamifyClient

client = NotamifyClient(token="YOUR_API_KEY")

# List all listeners
listeners = client.list_listeners()
for listener in listeners:
    print(f"{listener.name} ({listener.id}) — active: {listener.active}")

# Create a listener with filters
listener = client.create_listener(
    name="JFK Runway Monitor",
    webhook_url="https://your-server.com/webhooks/notamify",
    filters={
        "notam_icao": ["KJFK"],
        "category": ["RUNWAY"],
    },
    lifecycle_enabled=True,
    mode="prod",
)
print(f"Created listener: {listener.id}")

# Update a listener
updated = client.update_listener(
    listener.id,
    filters={
        "notam_icao": ["KJFK", "KEWR"],
        "category": ["AERODROME", "OBSTACLES"],
    },
)

# Delete a listener
client.delete_listener(listener.id)

# Sandbox testing — trigger a test delivery
result = client.send_sandbox_message(listener.id)
print(f"Sandbox delivery: {result}")

Use Notamify API key to validate the requests. Received webhook messages should be authenticated via Webhook Secret. Read more: Webhook Security

List listeners

get

Returns all registered listeners for the authenticated account.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

List of listeners

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

get/listeners

GET /listeners HTTP/1.1
Host: watcher.notamify.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "listeners": [
    {
      "id": "text",
      "team_id": "text",
      "name": "text",
      "webhook_url": "https://example.com",
      "emails": [
        "name@gmail.com"
      ],
      "filters": {
        "notam_icao": [
          "text"
        ],
        "notam_type": [
          "N"
        ],
        "airport_type": [
          "small_airport"
        ],
        "aircraft_type": [
          "text"
        ],
        "aircraft_designator": [
          "text"
        ],
        "aircraft_family": [
          "text"
        ],
        "category": [
          "all"
        ],
        "subcategory": [
          "RUNWAY_OPERATIONS"
        ],
        "qcode": [
          "text"
        ],
        "time_windows": [
          {
            "type": "relative",
            "days": [
              "MO"
            ],
            "start": "text",
            "end": "text",
            "start_at": "2026-08-11T12:20:23.099Z",
            "end_at": "2026-08-11T12:20:23.099Z"
          }
        ],
        "affected_element": [
          {
            "effect": "text",
            "type": "text",
            "subtype": "text",
            "identifier": "text",
            "applies_to": {
              "ANY_ADDITIONAL_PROPERTY": "text"
            },
            "changes": [
              {
                "subject": "text",
                "from": {
                  "operator": "text",
                  "value": 1,
                  "min": 1,
                  "max": 1,
                  "unit": "text"
                },
                "to": {
                  "operator": "text",
                  "value": 1,
                  "min": 1,
                  "max": 1,
                  "unit": "text"
                }
              }
            ]
          }
        ]
      },
      "lifecycle": {
        "enabled": true,
        "types": [
          "CANCELLED"
        ]
      },
      "metadata": {
        "notams_shipped": 1,
        "consecutive_delivery_failures": 1,
        "auto_paused_at": "2026-08-11T12:20:23.099Z"
      },
      "active": true,
      "mode": "prod",
      "created_at": "2026-08-11T12:20:23.099Z",
      "updated_at": "2026-08-11T12:20:23.099Z"
    }
  ]
}

Create listener

post

Registers a webhook URL and filters. Filters use OR within a field and AND across fields. For example, category=['AERODROME','AIRSPACE'] matches either category; combining with notam_icao=['EPWA'] requires both fields to match. Using category=['all'] matches any category. mode defaults to 'prod'. lifecycle.enabled controls separate notifications when previously delivered NOTAMs are later cancelled or replaced. lifecycle.types can narrow those events to cancelled and/or replaced. Each owner can have at most one active listener whose webhook host is trycloudflare.com or a subdomain of it.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

namestring · max: 100Optional

Optional human-readable name for the listener (max 100 characters).

webhook_urlstring · uriOptional

Destination HTTPS/HTTP endpoint for notifications. Must be a public URL, not localhost or private network ranges. Each owner can have at most one active trycloudflare.com webhook listener. Required when emails are omitted or empty.

emailsstring · email[] · max: 3Optional

Optional email recipients for notification delivery. Required when webhook_url is omitted.

activebooleanOptional

Whether the listener is active. Defaults to true if not provided. Set to false to temporarily disable notifications without deleting the listener.

Default: true

modestring · enumOptional

Listener delivery mode. 'prod' receives live matching events. 'sandbox' is for manual test sends only.

Default: prodPossible values:

Responses

201

Listener created

application/json

idstringRequired

team_idstringOptional

Team context when the listener was created or updated by a team-authenticated principal. Team-level alert email profiles apply only when this value is present.

namestring · max: 100Optional

Optional human-readable name for the listener (max 100 characters).

webhook_urlstring · uriOptional

Destination HTTPS/HTTP endpoint for notifications. Must be a public URL, not localhost or private network ranges. Each owner can have at most one active trycloudflare.com webhook listener.

emailsstring · email[] · max: 3Optional

Optional email recipients for notification delivery.

activebooleanRequired

Whether the listener is active and will receive notifications.

modestring · enumRequired

Listener delivery mode. 'prod' receives live matching events. 'sandbox' is for manual test sends only.

Possible values:

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

webhook_secretstringOptional

Webhook signing secret (returned once on creation/rotation).

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

post/listeners

POST /listeners HTTP/1.1
Host: watcher.notamify.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 245

{
  "name": "Warsaw & Heathrow Runway Closures",
  "webhook_url": "https://example.com/notam-webhook",
  "filters": {
    "notam_icao": [
      "EPWA",
      "EGLL"
    ],
    "category": [
      "AERODROME"
    ],
    "subcategory": [
      "RUNWAY_OPERATIONS"
    ]
  },
  "emails": [
    "pilot@example.com",
    "ops@example.com"
  ]
}

{
  "id": "text",
  "team_id": "text",
  "name": "text",
  "webhook_url": "https://example.com",
  "emails": [
    "name@gmail.com"
  ],
  "filters": {
    "notam_icao": [
      "text"
    ],
    "notam_type": [
      "N"
    ],
    "airport_type": [
      "small_airport"
    ],
    "aircraft_type": [
      "text"
    ],
    "aircraft_designator": [
      "text"
    ],
    "aircraft_family": [
      "text"
    ],
    "category": [
      "all"
    ],
    "subcategory": [
      "RUNWAY_OPERATIONS"
    ],
    "qcode": [
      "text"
    ],
    "time_windows": [
      {
        "type": "relative",
        "days": [
          "MO"
        ],
        "start": "text",
        "end": "text",
        "start_at": "2026-08-11T12:20:23.099Z",
        "end_at": "2026-08-11T12:20:23.099Z"
      }
    ],
    "affected_element": [
      {
        "effect": "text",
        "type": "text",
        "subtype": "text",
        "identifier": "text",
        "applies_to": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "changes": [
          {
            "subject": "text",
            "from": {
              "operator": "text",
              "value": 1,
              "min": 1,
              "max": 1,
              "unit": "text"
            },
            "to": {
              "operator": "text",
              "value": 1,
              "min": 1,
              "max": 1,
              "unit": "text"
            }
          }
        ]
      }
    ]
  },
  "lifecycle": {
    "enabled": true,
    "types": [
      "CANCELLED"
    ]
  },
  "metadata": {
    "notams_shipped": 1,
    "consecutive_delivery_failures": 1,
    "auto_paused_at": "2026-08-11T12:20:23.099Z"
  },
  "active": true,
  "mode": "prod",
  "created_at": "2026-08-11T12:20:23.099Z",
  "updated_at": "2026-08-11T12:20:23.099Z",
  "webhook_secret": "text"
}

Update listener

put

Updates webhook URL and/or filters using the same rules as creation. mode can be changed between 'prod' and 'sandbox'. lifecycle.enabled controls separate notifications when previously delivered NOTAMs are later cancelled or replaced. lifecycle.types can narrow those events to cancelled and/or replaced.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Listener ID

Body

namestring · max: 100Optional

Optional human-readable name for the listener (max 100 characters).

webhook_urlstring · uriOptional

emailsstring · email[] · max: 3Optional

Optional email recipients for notification delivery. Required when webhook_url is omitted.

activebooleanOptional

Whether the listener is active. Defaults to true if not provided. Set to false to temporarily disable notifications without deleting the listener.

Default: true

modestring · enumOptional

Listener delivery mode. 'prod' receives live matching events. 'sandbox' is for manual test sends only.

Default: prodPossible values:

Responses

200

Listener updated

application/json

idstringRequired

team_idstringOptional

Team context when the listener was created or updated by a team-authenticated principal. Team-level alert email profiles apply only when this value is present.

namestring · max: 100Optional

Optional human-readable name for the listener (max 100 characters).

webhook_urlstring · uriOptional

Destination HTTPS/HTTP endpoint for notifications. Must be a public URL, not localhost or private network ranges. Each owner can have at most one active trycloudflare.com webhook listener.

emailsstring · email[] · max: 3Optional

Optional email recipients for notification delivery.

activebooleanRequired

Whether the listener is active and will receive notifications.

modestring · enumRequired

Listener delivery mode. 'prod' receives live matching events. 'sandbox' is for manual test sends only.

Possible values:

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

put/listeners/{id}

PUT /listeners/{id} HTTP/1.1
Host: watcher.notamify.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 854

{
  "name": "text",
  "webhook_url": "https://example.com",
  "emails": [
    "name@gmail.com"
  ],
  "filters": {
    "notam_icao": [
      "text"
    ],
    "notam_type": [
      "N"
    ],
    "airport_type": [
      "small_airport"
    ],
    "aircraft_type": [
      "text"
    ],
    "aircraft_designator": [
      "text"
    ],
    "aircraft_family": [
      "text"
    ],
    "category": [
      "all"
    ],
    "subcategory": [
      "RUNWAY_OPERATIONS"
    ],
    "qcode": [
      "text"
    ],
    "time_windows": [
      {
        "type": "relative",
        "days": [
          "MO"
        ],
        "start": "text",
        "end": "text",
        "start_at": "2026-08-11T12:20:23.099Z",
        "end_at": "2026-08-11T12:20:23.099Z"
      }
    ],
    "affected_element": [
      {
        "effect": "text",
        "type": "text",
        "subtype": "text",
        "identifier": "text",
        "applies_to": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "changes": [
          {
            "subject": "text",
            "from": {
              "operator": "text",
              "value": 1,
              "min": 1,
              "max": 1,
              "unit": "text"
            },
            "to": {
              "operator": "text",
              "value": 1,
              "min": 1,
              "max": 1,
              "unit": "text"
            }
          }
        ]
      }
    ]
  },
  "lifecycle": {
    "enabled": false,
    "types": [
      "CANCELLED"
    ]
  },
  "active": true,
  "mode": "prod"
}

{
  "id": "text",
  "team_id": "text",
  "name": "text",
  "webhook_url": "https://example.com",
  "emails": [
    "name@gmail.com"
  ],
  "filters": {
    "notam_icao": [
      "text"
    ],
    "notam_type": [
      "N"
    ],
    "airport_type": [
      "small_airport"
    ],
    "aircraft_type": [
      "text"
    ],
    "aircraft_designator": [
      "text"
    ],
    "aircraft_family": [
      "text"
    ],
    "category": [
      "all"
    ],
    "subcategory": [
      "RUNWAY_OPERATIONS"
    ],
    "qcode": [
      "text"
    ],
    "time_windows": [
      {
        "type": "relative",
        "days": [
          "MO"
        ],
        "start": "text",
        "end": "text",
        "start_at": "2026-08-11T12:20:23.099Z",
        "end_at": "2026-08-11T12:20:23.099Z"
      }
    ],
    "affected_element": [
      {
        "effect": "text",
        "type": "text",
        "subtype": "text",
        "identifier": "text",
        "applies_to": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "changes": [
          {
            "subject": "text",
            "from": {
              "operator": "text",
              "value": 1,
              "min": 1,
              "max": 1,
              "unit": "text"
            },
            "to": {
              "operator": "text",
              "value": 1,
              "min": 1,
              "max": 1,
              "unit": "text"
            }
          }
        ]
      }
    ]
  },
  "lifecycle": {
    "enabled": true,
    "types": [
      "CANCELLED"
    ]
  },
  "metadata": {
    "notams_shipped": 1,
    "consecutive_delivery_failures": 1,
    "auto_paused_at": "2026-08-11T12:20:23.099Z"
  },
  "active": true,
  "mode": "prod",
  "created_at": "2026-08-11T12:20:23.099Z",
  "updated_at": "2026-08-11T12:20:23.099Z"
}

Delete listener

delete

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Listener ID

Responses

204

Deleted

No content

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

delete/listeners/{id}

DELETE /listeners/{id} HTTP/1.1
Host: watcher.notamify.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

PreviousBriefings chips system NextWatcher API Webhook messages

Last updated 19 days ago