Zum Inhalt springen

Webhook erstellen POST ​

Erstelle einen neuen Webhook, um Benachrichtigungen von externen Diensten zu empfangen.

Endpunkt ​

POST https://api.pocketalert.app/v1/webhooks

Authentifizierung ​

Erforderlich

Füge einen dieser Header in deiner Anfrage hinzu:

Anfrage ​

HeaderErforderlichBeschreibung
Token✅Dein API-Schlüssel
Authorization✅Bearer <jwt-token>

Body-Parameter ​

ParameterTypErforderlichBeschreibung
namestring✅Name des Webhooks (z. B. "Sentry", "GitHub")
urlstring❌Slug der Empfangs-URL https://p4a.me/wh/{url}. Wird ein Slug weggelassen, wird ein zufälliger 20-stelliger Slug erzeugt. Muss eindeutig sein: Ein bereits vergebener Slug liefert 409 zurück
messagestring✅Nachrichtenvorlage (verwende * für rohes JSON)
application_idstring❌Anwendungs-TID, um Nachrichten zu kategorisieren
device_idstring❌TID des Ziel-Geräts (weglassen für alle Geräte)
default_levelstring | int❌Standard-Prioritätsstufe für Nachrichten dieses Webhooks, wenn die Payload keine angibt: ein Name (silent, low, default, high, critical) oder eine Zahl (-2..2). Siehe Prioritätsstufen von Nachrichten.
actionsstring❌JSON-Vorlage für Aktionsbuttons. Gleicher Aufbau wie Nachrichten-Aktionen, aber label/value können %field.path%-Platzhalter enthalten, die anhand der eingehenden Payload aufgelöst werden. Wird als JSON-String gespeichert. Kostenpflichtige Funktion: Auf kostenlosen Tarifen wird sie entfernt.

Vorlage für Aktionsbuttons ​

actions ermöglicht es, dass webhook-generierte Benachrichtigungen bis zu 3 Buttons enthalten. Die Platzhalter %field.path% werden durch Werte aus der eingehenden Payload ersetzt (gleiche Syntax wie bei der Nachrichtenvorlage):

json
[
  { "type": "view", "label": "Open issue", "value": "%issue.html_url%" },
  { "type": "http", "label": "Ack", "value": "{\"url\":\"https://ops.example.com/ack/%issue.id%\",\"method\":\"POST\"}" }
]

Die Vorlage wird beim Speichern geprüft: Sie muss ein JSON-Array mit höchstens 3 Buttons mit gültigem type sein, und ein Button ohne Platzhalter muss vollständig gültig sein, sonst gibt die Anfrage 400 zurück.

Nach der Ersetzung wird jeder Button wie Nachrichten-Aktionen geprüft. Ein Button, der für diese Payload ungültig wird, etwa ein view-Button, dessen URL-Feld fehlt, wird einzeln verworfen; die übrigen Buttons und die Nachricht werden trotzdem zugestellt.

Aktionsbuttons sind eine kostenpflichtige Funktion. Auf kostenlosen Tarifen werden sie serverseitig entfernt, und die Nachricht wird ohne sie zugestellt.

Syntax der Nachrichtenvorlage ​

Verwende %field.path%, um Werte aus eingehendem JSON zu extrahieren:

VorlageBeschreibung
*Gesamte JSON-Payload ausgeben
%field%Feld der obersten Ebene extrahieren
%object.field%Verschachteltes Feld extrahieren
%array.0.field%Aus einem Array über den Index extrahieren
%%Ein wörtliches %. Nur nötig direkt vor einem Wort, auf das ein weiteres % folgt, etwa in %cpu%%%; ein % gefolgt von einem Leerzeichen, etwa in 90% on %host%, bleibt unverändert

Ausführliche Beispiele findest du unter Webhook-Einstellungen.

Beispielanfrage ​

bash
curl -X POST "https://api.pocketalert.app/v1/webhooks" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Push",
    "message": "Push to %repository.name%: %head_commit.message%",
    "application_id": "s9h1ekk5xb46jikthl"
  }'
javascript
const response = await fetch('https://api.pocketalert.app/v1/webhooks', {
  method: 'POST',
  headers: {
    'Token': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'GitHub Push',
    message: 'Push to %repository.name%: %head_commit.message%',
    application_id: 's9h1ekk5xb46jikthl'
  })
});

const webhook = await response.json();
console.log('Webhook URL:', `https://p4a.me/wh/${webhook.url}`);
python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/webhooks',
    headers={'Token': 'your-api-key'},
    json={
        'name': 'GitHub Push',
        'message': 'Push to %repository.name%: %head_commit.message%',
        'application_id': 's9h1ekk5xb46jikthl'
    }
)

webhook = response.json()
print(f"Webhook URL: https://p4a.me/wh/{webhook['url']}")
php
$response = Http::withHeaders([
    'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/webhooks', [
    'name' => 'GitHub Push',
    'message' => 'Push to %repository.name%: %head_commit.message%',
    'application_id' => 's9h1ekk5xb46jikthl',
]);

$webhook = $response->json();
echo 'Webhook URL: https://p4a.me/wh/'.$webhook['url'];

Antwort ​

Erfolgreiche Antwort ​

201 Created

Webhook erfolgreich erstellt

FeldTypBeschreibung
tidstringEindeutige Webhook-Kennung
namestringName des Webhooks
urlstringSlug der Webhook-URL — verwende ihn in externen Diensten
messagestringNachrichtenvorlage
actionsstringJSON-Vorlage für Aktionsbuttons (leer, wenn nicht gesetzt)
is_activebooleanOb der Webhook aktiv ist
json
{
  "tid": "kblf7mh9j8jjyeh4fx",
  "name": "GitHub Push",
  "url": "cs994rqfkk8ljngt",
  "message": "Push to %repository.name%: %head_commit.message%",
  "actions": "",
  "application_tid": "qm47b9pzxzx7applfd0",
  "device_tid": "",
  "is_active": true,
  "created_at": "01.09.2023 22:38:48"
}

Webhook verwenden

Konfiguriere deinen externen Dienst so, dass er per POST an folgende Adresse sendet:

https://p4a.me/wh/{url}

Fehlerantworten ​

StatusBeschreibung
400Ungültige Anfrage — fehlendes name oder message, ein ungültiges default_level oder eine ungültige actions-Vorlage
401Nicht autorisiert — ungültiger oder fehlender Token
403Verboten — Webhook-Limit deines Tarifs erreicht
404Nicht gefunden — application_id oder device_id existiert nicht
409Konflikt — der url-Slug ist bereits vergeben

Pocket Alert Dokumentation