Webhooks

Webhooks let Upper push notifications to your own system as things happen in your account — instead of you having to poll the API for changes. You register a receiver URL, and when a relevant event occurs (for example, a stop is updated), Upper sends an HTTP request to that URL with details about the event. Each delivery attempt is recorded so you can review what was sent and whether it succeeded.

There are two parts to working with webhooks:

Registering receiver URLs — where Upper should send notifications.
Reviewing delivery history — what Upper has sent and the outcome of each attempt.

The webhook management endpoints below (/user-webhooks and /user-webhook-history) are used by the Upper web app and authenticate through your logged-in app session, not the x-api-token header used by the public ext-* endpoints. The supported, end-user way to register and review webhooks is the Settings → Webhooks screen in the app. The reference below documents the underlying endpoints for completeness. For token-authenticated public endpoints, see Authentication.

Register a receiver URL (Settings → Webhooks)

The simplest way to register where Upper should send webhook notifications is in the app:

Open Settings → Webhooks.
Add the receiver URL(s) you want Upper to call. Each URL is stored against your account as the l_webhook_url field.
Save. Upper will begin sending event notifications to the registered URL(s).

This same screen is where your API Token lives (used for the public ext-* endpoints).

There is a maximum number of webhook receiver URLs you can register per account. The exact limit is enforced by the app and is pending confirmation — if you hit the cap, remove an unused URL before adding a new one.

Manage webhook URLs (endpoint)

POST /api/v1/user-webhooks

Authentication: logged-in app session (not x-api-token).

This single endpoint lists your registered webhook URLs and also accepts changes — adding new URLs, updating existing ones, and deleting them — in the same request body.

Parameters

The request body is JSON. All fields are optional; send only the ones you need.

Name	Type	Required	Description
`search.keyword`	string	No	Filter the returned list to URLs matching this keyword (matched against `l_webhook_url`).
`sort.by`	string	No	Column to sort by (for example `id`).
`sort.order`	string	No	Sort direction: `asc` or `desc` (defaults to `desc`).
`update`	array	No	List of URL objects to add or update. Include `id` to update an existing row; omit `id` to create a new one.
`update[].id`	integer	No	The id of an existing webhook URL to update. Omit to create a new URL.
`update[].l_webhook_url`	string	No	The webhook receiver URL value to store.
`delete`	array	No	List of webhook URL ids to delete.
`page`	integer	No	Page number (query parameter). When present, results are paginated.
`limit`	integer	No	Page size when paginating (query parameter).

Example request

curl -X POST "https://teamapi.upperinc.com/api/v1/user-webhooks" \
  -H "Content-Type: application/json" \
  --cookie "your-app-session-cookie" \
  -d '{
    "update": [
      { "l_webhook_url": "https://example.com/hooks/upper" }
    ],
    "sort": { "by": "id", "order": "desc" }
  }'

Example response

{
  "code": 200,
  "message": "Data fetched successfully.",
  "data": [
    {
      "id": 7,
      "i_user_id": 1024,
      "l_webhook_url": "https://example.com/hooks/upper",
      "v_api_version": "v1",
      "e_row_status": 1
    }
  ]
}

The exact set of columns returned for each webhook row reflects the tbl_user_webhooks table; the fields shown above (id, i_user_id, l_webhook_url, v_api_version, e_row_status) are those set or read by the endpoint. Additional timestamp columns may also be present.

What Upper sends to your URL

When a relevant event occurs, Upper sends an HTTP request to your registered URL and records the attempt in your webhook history. The delivery is dispatched as a background job, so it arrives shortly after the event rather than blocking the action that triggered it.

The full catalog of webhook event names and the exact payload schema is pending confirmation and is not derivable from the source reviewed for this page. The example below is representative only — treat the field names as illustrative, not guaranteed. One event observed in the code is a stop-update notification (internally referenced as stop.updated). Do not rely on specific event names until the official event catalog is published.

{
  "event": "stop.updated",
  "data": {
    "...": "event-specific fields (schema pending confirmation)"
  }
}

Review delivery history (endpoint)

POST /api/v1/user-webhook-history

Authentication: logged-in app session (not x-api-token).

Returns the record of webhook deliveries for your account, joined with the receiver URL (l_webhook_url) each delivery was sent to. As with the management endpoint, the history is also surfaced in the Settings → Webhooks area of the app.

Parameters

The request body is JSON. All fields are optional.

Name	Type	Required	Description
`search.keyword`	string	No	Filter history to entries whose webhook URL (`l_webhook_url`) matches this keyword.
`sort.by`	string	No	Column to sort by (applied to the webhook history table).
`sort.order`	string	No	Sort direction: `asc` or `desc` (defaults to `desc`).
`update`	array	No	List of objects with an `id` to re-trigger a stop-update webhook delivery for that history entry.
`update[].id`	integer	No	The id used to dispatch the re-send.
`page`	integer	No	Page number (query parameter). When present, results are paginated.
`limit`	integer	No	Page size when paginating (query parameter).