Aller au contenu

Créer un webhook POST ​

Créez un nouveau webhook pour recevoir des notifications push depuis des services externes.

Point de terminaison ​

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

Authentification ​

Obligatoire

Incluez l’un de ces en-têtes dans votre requête :

  • Token: <your-api-key> — Obtenez-la depuis Clés API
  • Authorization: Bearer <jwt-token> — Depuis Connexion

Requête ​

En-têtes ​

En-têteObligatoireDescription
Token✅Votre clé API
Authorization✅Bearer <jwt-token>

Paramètres du corps ​

ParamètreTypeObligatoireDescription
namestring✅Nom du webhook (par ex. « Sentry », « GitHub »)
urlstring❌Slug de l’URL de réception https://p4a.me/wh/{url}. Un slug aléatoire de 20 caractères est généré si ce champ est omis. Il doit être unique : un slug déjà pris renvoie 409
messagestring✅Modèle de message (utilisez * pour le JSON brut)
application_idstring❌TID de l’application pour classer les messages
device_idstring❌TID de l’appareil cible (omettez-le pour tous les appareils)
default_levelstring | int❌Niveau de priorité par défaut appliqué aux messages de ce webhook lorsque la charge utile n’en précise pas : un nom (silent, low, default, high, critical) ou un entier (-2..2). Voir Niveaux de priorité des messages.
actionsstring❌Modèle JSON de boutons d’action. Même structure que les actions de message, mais label/value peuvent contenir des espaces réservés %field.path% résolus à partir de la charge utile entrante. Stocké sous forme de chaîne JSON. Fonctionnalité payante : supprimée sur l’offre gratuite.

Modèle de boutons d’action ​

actions permet aux notifications générées par le webhook de comporter jusqu’à 3 boutons, avec des espaces réservés %field.path% remplacés par les valeurs de la charge utile entrante (même syntaxe que le modèle de message) :

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\"}" }
]

Le modèle est vérifié lors de l’enregistrement : il doit être un tableau JSON d’au plus 3 boutons, avec un type valide, et un bouton sans espace réservé doit être entièrement valide, sans quoi la requête renvoie 400.

Après remplacement, chaque bouton est validé comme les actions de message. Un bouton devenu invalide pour cette charge utile, comme un bouton view dont le champ d’URL est absent, est supprimé à lui seul ; les autres boutons et le message sont tout de même envoyés.

Les boutons d’action sont une fonctionnalité payante. Sur l’offre gratuite, ils sont supprimés côté serveur et le message est envoyé sans eux.

Syntaxe du modèle de message ​

Utilisez %field.path% pour extraire des valeurs du JSON entrant :

ModèleDescription
*Affiche la charge utile JSON complète
%field%Extrait un champ de premier niveau
%object.field%Extrait un champ imbriqué
%array.0.field%Extrait depuis un tableau par index
%%Un % littéral. Nécessaire uniquement juste avant un mot suivi d’un autre %, comme dans %cpu%%% ; un % suivi d’une espace, comme dans 90% on %host%, reste tel quel

Consultez Paramètres du webhook pour des exemples détaillés.

Exemple de requête ​

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'];

Réponse ​

Réponse de succès ​

201 Created

Webhook créé avec succès

ChampTypeDescription
tidstringIdentifiant unique du webhook
namestringNom du webhook
urlstringSlug de l’URL du webhook — à utiliser dans les services externes
messagestringModèle de message
actionsstringModèle JSON des boutons d’action (vide si non défini)
is_activebooleanIndique si le webhook est actif
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"
}

Utiliser votre webhook

Configurez votre service externe pour envoyer une requête POST à :

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

Réponses d’erreur ​

StatutDescription
400Requête incorrecte — name ou message manquant, default_level invalide ou modèle actions invalide
401Non autorisé — jeton invalide ou manquant
403Interdit — limite de webhooks de votre offre atteinte
404Introuvable — application_id ou device_id inexistant
409Conflit — le slug url est déjà pris

Documentation de Pocket Alert