Trigger-API-Referenz
Zeitplan- und Webhook-Trigger-Endpunkte: die Bodies beider Arten, Secret-Rotation, das Firings-Log und der signierte öffentliche Zustell-Endpunkt.
Zuletzt aktualisiert:
Trigger starten Workflow-Läufe, ohne dass du eingreifst: nach Cron-Plan oder wenn ein externes System einen signierten Webhook zustellt. Alles unten außer dem Zustell-Endpunkt selbst nimmt einen API-Schlüssel als Bearer-Token; der Zustell-Endpunkt ist die einzige öffentliche Route der API und authentifiziert stattdessen per HMAC.
/v1/workflows/:id/triggers
Erzeugt einen Trigger am Workflow; das `kind` im Body entscheidet, welche der beiden Formen unten gilt.
Zeitplan-Body
| Name | Typ | Beschreibung |
|---|---|---|
kind
erforderlich
|
string | `schedule`. |
name
|
string | Ein Label für den Trigger. |
cron
erforderlich
|
string | Ein Cron-Ausdruck; das Mindestintervall zwischen Fälligkeiten beträgt 5 Minuten. |
timezone
erforderlich
|
string | Eine IANA-Zone wie `Europe/Berlin` — nie ein UTC-Offset. Wanduhrzeit ist wörtlich gemeint: Am Tag der Zeitumstellung zurück feuert ein täglicher Job einmal, und ein Job in der Frühjahrslücke feuert, wenn die Lücke endet. |
catchUp
|
string | `skip` oder `run_once`. Egal wie lange die Plattform down war, eine Entscheidung: verpasste Fälligkeiten fallen lassen oder einen einzelnen Nachhol-Lauf feuern. |
misfireGraceSeconds
|
integer |
60 bis 21600 — wie spät eine Fälligkeit noch feuern darf, bevor sie als verpasst gilt.
Standard: 300
|
overlap
|
string | `skip` oder `allow`: was passiert, wenn der vorige Lauf noch läuft. |
inputs
|
object | Eingaben, die jedem Lauf mitgegeben werden. |
session
|
object | Wie die Session für jeden Lauf erzeugt wird: `{poolId, profileId, locale, timezone, ttlSeconds}`. |
version
|
integer | Heftet die Läufe des Triggers an eine Workflow-Version. |
Webhook-Body
| Name | Typ | Beschreibung |
|---|---|---|
kind
erforderlich
|
string | `webhook`. |
name
|
string | Ein Label für den Trigger. |
inputs
|
object | Eingaben für die Läufe, die dieser Trigger startet. |
session
|
object | Session-Einstellungen je Lauf, gleiche Form wie beim Zeitplan-Trigger. |
Ein Secret, einmal gezeigt
Das Anlegen eines Webhook-Triggers antwortet mit 201, dem Trigger und einem secret, das mit whs_ beginnt — zurückgegeben genau einmal, bei der Erstellung. Speichere es dann; danach meldet der Trigger nur noch hasSecret, und der Weg zurück ist Rotation, nicht Auslesen.
/v1/triggers
Listet Trigger, eingegrenzt über den Query-Parameter `workflowId`.
/v1/triggers/:id
Liest einen Trigger, bei Zeitplänen inklusive `nextFireAt`.
/v1/triggers/:id
Aktualisiert einen Trigger, einschließlich des Umschaltens von `status` zwischen `active` und `paused`.
/v1/triggers/:id
Löscht den Trigger.
/v1/triggers/:id/secret
Rotiert das Webhook-Secret und gibt das neue zurück.
Rotations-Body
| Name | Typ | Beschreibung |
|---|---|---|
graceSeconds
|
integer | 0 bis 604800 — wie lange das bisherige Secret noch akzeptiert wird; die Antwort nennt den Stichtag als `previousSecretUntil`. |
/v1/triggers/:id/firings
Listet jede Gelegenheit, zu der der Trigger fällig war — auch die, bei denen nichts lief.
Warum letzte Nacht nichts lief
Das outcome eines Firings ist started, skipped oder refused. Übersprungenes und Verweigertes wird absichtlich festgehalten: Dieses Log beantwortet die Frage, an der ein stummer Scheduler scheitert — eine von overlap: skip unterdrückte Fälligkeit, eine jenseits der Misfire-Frist verpasste oder eine rundheraus verweigerte hinterlassen hier je eine Zeile, die es sagt.
/v1/trigger-hooks/:id
Nimmt eine signierte Zustellung von außen entgegen — der einzige Endpunkt der API ohne API-Schlüssel.
Zustell-Header
| Name | Typ | Beschreibung |
|---|---|---|
x-browserberg-delivery
erforderlich
|
header | Deine Zustell-ID, bis 200 Zeichen — der Dedup-Schlüssel: Eine wiederholte ID startet keinen zweiten Lauf. |
x-browserberg-timestamp
erforderlich
|
header | Unix-Sekunden zum Signierzeitpunkt; Zustellungen außerhalb eines Fensters von ±300 Sekunden werden abgelehnt. |
x-browserberg-signature
erforderlich
|
header | HMAC-SHA256 als Hex in Kleinbuchstaben, optional mit Präfix `v1=`. |
Wie eine Zustellung geprüft wird
Die Signatur wird über deliveryId.timestamp.rawBody berechnet — die rohen Bytes, die du sendest, nie eine Re-Serialisierung — und die Zustell-ID liegt unter der Signatur, damit eine abgefangene Zustellung nicht unter frischen IDs wiederholt werden kann. Content-Type muss application/json sein, und der Endpunkt nimmt höchstens 60 Zustellungen pro Minute und IP an. Unbekannter Trigger, falsche Signatur und nicht entschlüsselbares Secret erzeugen ein und dieselbe 401, ein Sondieren lernt also nichts. Eine Zustellung, die einen Lauf startet, antwortet mit 202 und dem Firing; eine übersprungene oder verweigerte mit 200.
Ein Nachtplan in einem Skript
Legt einen Workflow an, hängt einen Zeitplan in Berliner Zeit daran und liest den Trigger zurück, bevor aufgeräumt wird.
Voraussetzungen: api-key
BASE="https://browserberg.com"
AUTH="Authorization: Bearer $BROWSERBERG_API_KEY"
JSON="Content-Type: application/json"
WFID=$(curl -s -X POST "$BASE/v1/workflows" -H "$AUTH" -H "$JSON" -d '{
"title": "Nightly example check",
"blocks": [ { "blockType": "navigation", "label": "Open_page", "url": "https://example.com" } ]
}' | python3 -c 'import json,sys; print(json.load(sys.stdin)["workflow"]["workflowId"])')
# A schedule is a cron expression plus an IANA zone -- never a UTC offset.
# Wall-clock time is meant literally, including on the DST switch days.
TRIGGER=$(curl -s -X POST "$BASE/v1/workflows/$WFID/triggers" -H "$AUTH" -H "$JSON" -d '{
"kind": "schedule",
"name": "Nightly at 02:30 Berlin time",
"cron": "30 2 * * *",
"timezone": "Europe/Berlin",
"catchUp": "run_once",
"session": { "ttlSeconds": 900 }
}')
echo "$TRIGGER" | python3 -c 'import json,sys; t = json.load(sys.stdin)["trigger"]; print(json.dumps({
"id": t["id"], "status": t["status"], "nextFireAt": t["nextFireAt"],
"catchUp": t["catchUp"], "overlap": t["overlap"]}, indent=2))'
TID=$(echo "$TRIGGER" | python3 -c 'import json,sys; print(json.load(sys.stdin)["trigger"]["id"])')
curl -s -X DELETE "$BASE/v1/triggers/$TID" -H "$AUTH" > /dev/null