Webhook erstellen POST
Erstelle einen neuen Webhook, um Benachrichtigungen von externen Diensten zu empfangen.
Endpunkt
POST https://api.pocketalert.app/v1/webhooksAuthentifizierung
Erforderlich
Füge einen dieser Header in deiner Anfrage hinzu:
Token: <your-api-key>— Hol ihn dir unter API-SchlüsselAuthorization: Bearer <jwt-token>— Aus Anmeldung
Anfrage
Header
| Header | Erforderlich | Beschreibung |
|---|---|---|
Token | ✅ | Dein API-Schlüssel |
Authorization | ✅ | Bearer <jwt-token> |
Body-Parameter
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
name | string | ✅ | Name des Webhooks (z. B. "Sentry", "GitHub") |
url | string | ❌ | 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 |
message | string | ✅ | Nachrichtenvorlage (verwende * für rohes JSON) |
application_id | string | ❌ | Anwendungs-TID, um Nachrichten zu kategorisieren |
device_id | string | ❌ | TID des Ziel-Geräts (weglassen für alle Geräte) |
default_level | string | 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. |
actions | string | ❌ | 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):
[
{ "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:
| Vorlage | Beschreibung |
|---|---|
* | 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
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"
}'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}`);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']}")$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
| Feld | Typ | Beschreibung |
|---|---|---|
tid | string | Eindeutige Webhook-Kennung |
name | string | Name des Webhooks |
url | string | Slug der Webhook-URL — verwende ihn in externen Diensten |
message | string | Nachrichtenvorlage |
actions | string | JSON-Vorlage für Aktionsbuttons (leer, wenn nicht gesetzt) |
is_active | boolean | Ob der Webhook aktiv ist |
{
"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
| Status | Beschreibung |
|---|---|
400 | Ungültige Anfrage — fehlendes name oder message, ein ungültiges default_level oder eine ungültige actions-Vorlage |
401 | Nicht autorisiert — ungültiger oder fehlender Token |
403 | Verboten — Webhook-Limit deines Tarifs erreicht |
404 | Nicht gefunden — application_id oder device_id existiert nicht |
409 | Konflikt — der url-Slug ist bereits vergeben |