Use a webhook trigger to start the execution of a notebook or report from an external app or process. Whenever the webhook URL is called, a new run will be started.

Setting Up a Webhook

In a Notebook

Open the sidebar and look for the Triggers section. Click Edit next to the webhook URL to configure it.

Webhook trigger in the notebook sidebar

In a Report

In the report editor, scroll down to the Schedule section. The webhook trigger is managed alongside the schedule settings.

Webhook trigger in the report editor

How It Works

When you create a webhook, PushMetrics generates a unique URL and a security token. Send a POST request to the URL and pass the token in the Authorization header as a Bearer token:

POST https://app.pushmetrics.io/api/v1/report/{report_id}/webhook
Authorization: Bearer {token}

curl -X POST \
  "https://app.pushmetrics.io/api/v1/report/{report_id}/webhook" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{}'

Keep the token out of the URL: a token in the query string can leak through server access logs, browser history and the Referer header. Calling the webhook triggers a new execution of the notebook or report. The execution runs asynchronously — the webhook returns immediately while the workflow runs in the background.

Passing Parameters

You can pass parameters in the POST body (JSON) to control the execution flow. These are injected into the workflow and can override Parameter blocks.

curl -X POST \
  "https://app.pushmetrics.io/api/v1/report/{report_id}/webhook" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"date": "2026-01-01", "region": "EMEA"}'

You can also pass parameters as query parameters on the URL (any parameter besides token):

https://app.pushmetrics.io/api/v1/report/{report_id}/webhook?date=2026-01-01&region=EMEA

Parameters passed via the webhook are available in your blocks just like regular Parameter blocks. If a parameter name matches an existing Parameter block, the webhook value overrides it.

Legacy: token in the URL (deprecated)

Older integrations pass the token in the query string and may call the webhook with GET:

https://app.pushmetrics.io/api/v1/report/{report_id}/webhook?token={token}

This form still works today but is deprecated because it exposes the token in logs and history. Move your callers to the Authorization header shown above; support for the query-string token will be removed in a future release.

Notifications

You can optionally configure notifications for webhook-triggered executions:

  • Email notifications — receive an email on success or failure. Add one or more email addresses as recipients.
  • Slack notifications — send a notification to a Slack channel when the execution completes or fails (requires an integration for Slack).

Managing Webhooks

  • Enable/disable — toggle the webhook on or off without deleting it. Disabled webhooks return an error when called.
  • Refresh token — generate a new token if the current one is compromised. The old token stops working immediately.
  • Copy URL / header — copy the webhook URL and the Authorization header value to your clipboard.

Use Cases

  • Trigger from CI/CD pipelines — run a report after a deployment completes.
  • External scheduler — use an external tool (Airflow, cron, etc.) to trigger PushMetrics workflows.
  • Event-driven execution — trigger a report when new data arrives in your warehouse.
  • On-demand reports — let an internal tool request a report generation via API.