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/webhooksAuthentification
Obligatoire
Incluez l’un de ces en-têtes dans votre requête :
Requête
En-têtes
| En-tête | Obligatoire | Description |
|---|---|---|
Token | ✅ | Votre clé API |
Authorization | ✅ | Bearer <jwt-token> |
Paramètres du corps
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
name | string | ✅ | Nom du webhook (par ex. « Sentry », « GitHub ») |
url | string | ❌ | 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 |
message | string | ✅ | Modèle de message (utilisez * pour le JSON brut) |
application_id | string | ❌ | TID de l’application pour classer les messages |
device_id | string | ❌ | TID de l’appareil cible (omettez-le pour tous les appareils) |
default_level | string | 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. |
actions | string | ❌ | 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) :
[
{ "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èle | Description |
|---|---|
* | 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
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'];Réponse
Réponse de succès
201 Created
Webhook créé avec succès
| Champ | Type | Description |
|---|---|---|
tid | string | Identifiant unique du webhook |
name | string | Nom du webhook |
url | string | Slug de l’URL du webhook — à utiliser dans les services externes |
message | string | Modèle de message |
actions | string | Modèle JSON des boutons d’action (vide si non défini) |
is_active | boolean | Indique si le webhook est actif |
{
"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
| Statut | Description |
|---|---|
400 | Requête incorrecte — name ou message manquant, default_level invalide ou modèle actions invalide |
401 | Non autorisé — jeton invalide ou manquant |
403 | Interdit — limite de webhooks de votre offre atteinte |
404 | Introuvable — application_id ou device_id inexistant |
409 | Conflit — le slug url est déjà pris |