Saltar al contenido

Crear webhook POST ​

Crea un nuevo webhook para recibir notificaciones de servicios externos.

Endpoint ​

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

Autenticación ​

Obligatorio

Incluye una de estas cabeceras en tu solicitud:

Solicitud ​

Cabeceras ​

CabeceraObligatoriaDescripción
Token✅Tu clave de API
Authorization✅Bearer <jwt-token>

Parámetros del cuerpo ​

ParámetroTipoObligatorioDescripción
namestring✅Nombre del webhook (p. ej., "Sentry", "GitHub")
urlstring❌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
messagestring✅Plantilla del mensaje (usa * para el JSON sin procesar)
application_idstring❌TID de la aplicación para clasificar los mensajes
device_idstring❌TID del dispositivo de destino (omítelo para todos los dispositivos)
default_levelstring | 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.
actionsstring❌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):

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

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:

PlantillaDescripció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 ​

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

Respuesta ​

Respuesta correcta ​

201 Created

Webhook creado correctamente

CampoTipoDescripción
tidstringIdentificador único del webhook
namestringNombre del webhook
urlstringSlug de la URL del webhook — úsalo en los servicios externos
messagestringPlantilla del mensaje
actionsstringPlantilla JSON de botones de acción (vacía si no se ha definido)
is_activebooleanIndica si el webhook está activo
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"
}

Usar tu webhook

Configura tu servicio externo para enviar un POST a:

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

Respuestas de error ​

EstadoDescripción
400Solicitud incorrecta — falta name o message, default_level no es válido o la plantilla actions no es válida
401No autorizado — token no válido o ausente
403Prohibido — se ha alcanzado el límite de webhooks de tu plan
404No encontrado — application_id o device_id no existe
409Conflicto — el slug url ya está en uso

Documentación de Pocket Alert