Crear webhook POST
Crea un nuevo webhook para recibir notificaciones de servicios externos.
Endpoint
POST https://api.pocketalert.app/v1/webhooksAutenticación
Obligatorio
Incluye una de estas cabeceras en tu solicitud:
Token: <your-api-key>— Obténla en Claves de APIAuthorization: Bearer <jwt-token>— Desde Iniciar sesión
Solicitud
Cabeceras
| Cabecera | Obligatoria | Descripción |
|---|---|---|
Token | ✅ | Tu clave de API |
Authorization | ✅ | Bearer <jwt-token> |
Parámetros del cuerpo
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
name | string | ✅ | Nombre del webhook (p. ej., "Sentry", "GitHub") |
url | string | ❌ | Slug de la URL de recepción https://p4a.me/wh/{url}. Si lo omites, se genera un slug aleatorio de 20 caracteres. Debe ser único: si el slug ya está en uso, la respuesta es 409 |
message | string | ✅ | Plantilla del mensaje (usa * para el JSON sin procesar) |
application_id | string | ❌ | TID de la aplicación para clasificar los mensajes |
device_id | string | ❌ | TID del dispositivo de destino (omítelo para todos los dispositivos) |
default_level | string | int | ❌ | Prioridad predeterminada que se aplica a los mensajes de este webhook cuando el payload no especifica una: un nombre (silent, low, default, high, critical) o un entero (-2..2). Consulta Niveles de prioridad de los mensajes. |
actions | string | ❌ | Plantilla JSON de botones de acción. Tiene la misma estructura que las acciones del mensaje, pero label/value pueden contener marcadores %field.path% que se resuelven con el payload entrante. Se guarda como cadena JSON. Función de pago: se elimina en los planes gratuitos. |
Plantilla de botones de acción
actions permite que las notificaciones generadas por el webhook incluyan hasta 3 botones, con marcadores %field.path% sustituidos por datos del payload entrante (misma sintaxis que la plantilla del mensaje):
[
{ "type": "view", "label": "Open issue", "value": "%issue.html_url%" },
{ "type": "http", "label": "Ack", "value": "{\"url\":\"https://ops.example.com/ack/%issue.id%\",\"method\":\"POST\"}" }
]La plantilla se comprueba al guardarla: debe ser un array JSON de como máximo 3 botones con un type válido, y un botón sin marcadores debe ser completamente válido; de lo contrario, la solicitud devuelve 400.
Después de la sustitución, cada botón se valida como las acciones del mensaje. Un botón que resulte inválido para ese payload, como un botón view cuyo campo de URL falta, se descarta por sí solo; los demás botones y el mensaje se siguen entregando.
Los botones de acción son una función de pago. En los planes gratuitos se eliminan en el servidor y el mensaje se entrega sin ellos.
Sintaxis de la plantilla del mensaje
Usa %field.path% para extraer valores del JSON entrante:
| Plantilla | Descripción |
|---|---|
* | Muestra el payload JSON completo |
%field% | Extrae un campo de nivel superior |
%object.field% | Extrae un campo anidado |
%array.0.field% | Extrae de un array por índice |
%% | Un % literal. Solo es necesario justo antes de una palabra seguida de otro %, como en %cpu%%%; un % seguido de un espacio, como en 90% on %host%, se mantiene tal cual |
Consulta Configuración del webhook para ver ejemplos detallados.
Ejemplo de solicitud
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'];Respuesta
Respuesta correcta
201 Created
Webhook creado correctamente
| Campo | Tipo | Descripción |
|---|---|---|
tid | string | Identificador único del webhook |
name | string | Nombre del webhook |
url | string | Slug de la URL del webhook — úsalo en los servicios externos |
message | string | Plantilla del mensaje |
actions | string | Plantilla JSON de botones de acción (vacía si no se ha definido) |
is_active | boolean | Indica si el webhook está activo |
{
"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"
}Usar tu webhook
Configura tu servicio externo para enviar un POST a:
https://p4a.me/wh/{url}Respuestas de error
| Estado | Descripción |
|---|---|
400 | Solicitud incorrecta — falta name o message, default_level no es válido o la plantilla actions no es válida |
401 | No autorizado — token no válido o ausente |
403 | Prohibido — se ha alcanzado el límite de webhooks de tu plan |
404 | No encontrado — application_id o device_id no existe |
409 | Conflicto — el slug url ya está en uso |