TP-Link Omada: webhook setup

Last updated:

TP-Link Omada: webhook setup

The Omada Open API does not expose alerts, events or notifications. The only reliable way to surface controller side alerts (device offline, IPS / potential attack, client blocked, system errors) in Chorum is the Omada Cloud Webhooks feature.

This article walks through the one-time configuration. After this, real time alerts land in /helpdesk/alerts with severity mapped automatically and the original payload preserved for forensics.

Prerequisites

  • You have an Omada integration created in Chorum (Helpdesk > Settings > Integrations). The wizard captures Open API client ID + secret + site selection.
  • You have admin access to the customer's Omada Cloud account at omada.tplinkcloud.com.
  • Customer container has BACKEND_URL set in the backend .env (used to build the absolute webhook URL).

Step 1: Copy the webhook URL from Chorum

  1. Open Helpdesk > Settings > Integrations.
  2. Click the Omada integration row to expand it.
  3. At the top of the expanded panel, the Inbound webhook card shows the URL. Click Copy.

The URL looks like this (token baked in):

https://<customer>.chorum.io/api/helpdesk/integrations/<integration-id>/webhook/omada/<token>

Step 2: Create the webhook in Omada

  1. Sign in to omada.tplinkcloud.com.
  2. Pick the Organisation that owns the customer's controller.
  3. Open Settings > Webhooks.
  4. Click Create New Webhook.
  5. Fill in:
    • Name: anything descriptive, e.g. Chorum Alerts.
    • Shared Secret: leave blank. Token authentication is via the URL path.
    • URL: paste the URL you copied from Chorum.
    • Payload Template: Omada.
    • Retry Policy: pick Critical if available, for up to 5 retries over 24 hours.
  6. Click Create.

Step 3: Verify

  1. In Omada, trigger any small event: unplug an access point briefly, or run Omada's webhook Test button if present.
  2. In Chorum, refresh /helpdesk/alerts. The alert should appear within a few seconds.
  3. The alert will show:
    • Provider: OMADA.
    • Title: prefixed with the Omada site name, suffixed with the device name if Omada included one.
    • Severity: derived from Omada's level field, or bumped to CRITICAL if the body contains threat keywords (attack, intrusion, IPS, malicious, port scan, etc.).
    • Raw payload: stored verbatim on the alert, viewable in the triage panel.

What Chorum does with the alert

  • Dedup: identical alerts within the flap window are folded into the existing record with an occurrence counter.
  • Service mapping: if the integration's company has matching service alert sources, the alert auto links to the right CustomerService.
  • Notification fan out: every helpdesk user gets an in app notification.
  • Automation trigger: the visual builder fires helpdesk.alert_received, so tenant specific flows (Teams page, auto raise ticket, etc.) run automatically.

Rotating the token

If a webhook URL leaks (logged somewhere it should not be, shared in a screenshot, etc.):

  1. In Chorum, expand the Omada integration row.
  2. Click Rotate token in the Inbound webhook card.
  3. Copy the new URL.
  4. Edit the Omada webhook and paste the new URL over the old one.

Any alerts pushed against the old URL after rotation return 400 and are dropped.

On premise / self hosted Omada controllers

The Omada Cloud Webhooks UI does not let you set custom headers. On premise controllers (Omada Software Controller, OC200, OC300) running 5.x often do allow custom headers. For those, prefer the header authentication variant:

  1. In the Inbound webhook card, click Show header auth variant.
  2. Use the shorter URL (no token in the path).
  3. Add a custom header to the Omada webhook: X-Webhook-Token = the token value.

Header based authentication keeps the token out of access logs, so it is preferred when supported.

Troubleshooting

  • No alerts appear after a real event: check Omada's webhook delivery log (Webhooks > the row > Logs). Look for HTTP status. 202 means Chorum accepted it. 400 means token rejected (URL stale after rotation?). 5xx means backend error, check pm2 logs chorum-backend.
  • Severity is wrong: Omada's level field is mapped 0 to CRITICAL, 1 to WARNING, 2 to INFO. If Omada omits the level entirely, the receiver scans the body for threat keywords and bumps to CRITICAL on match. If your alert is consistently miscategorised, send the raw payload from the alert detail page and we can tune the parser.
  • The wizard told me BACKEND_URL is unset: in the container, edit /home/ubuntu/Chorum.io/backend/.env and add BACKEND_URL=https://customer.chorum.io. Restart pm2. The URL in the Inbound webhook card will become absolute on next page load.
  • Webhook fires but the alert is marked unmatched in the queue: the integration is not linked to a CustomerService alert source. Triage the alert once via the queue's Triage button to create a reusable mapping. Future alerts with the same provider plus external ID will auto resolve.

Why not the Open API?

We probed the Omada Open API exhaustively. The /alerts, /notifications, /events, /logs/* and /threats paths all return 404 or 400 with a generic Spring error. The official spec confirms it: the only log adjacent route is /remote-logging, which is syslog configuration, not log retrieval. An undocumented v2 session API exists (/api/v2/sites/<key>/alerts) but it requires username and password, CSRF tokens, and breaks on every controller upgrade. Webhooks are the only stable channel.