Create Webhook POST

Create a new webhook to receive notifications from external services.

Endpoint

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

Authentication

Required

Include one of these headers in your request:

• Token: <your-api-key> — Get it from API Keys
• Authorization: Bearer <jwt-token> — From Login

Request

Headers

Header	Required	Description
Token	✅	Your API key
Authorization	✅	Bearer <jwt-token>

Body Parameters

Parameter	Type	Required	Description
name	string	✅	Webhook name (e.g., "Sentry", "GitHub")
message	string	✅	Message template (use * for raw JSON)
application_id	string	❌	Application TID to categorize messages
device_id	string	❌	Target device TID (omit for all devices)

Message Template Syntax

Use %field.path% to extract values from incoming JSON:

Template	Description
*	Output entire JSON payload
%field%	Extract top-level field
%object.field%	Extract nested field
%array.0.field%	Extract from array by index

See Webhook Settings for detailed examples.

Example Request

cURL

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://api.pocketalert.app/v1/webhooks/receive/${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://api.pocketalert.app/v1/webhooks/receive/{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://api.pocketalert.app/v1/webhooks/receive/'.$webhook['url'];

Response

Success Response

201 Created

Webhook created successfully

Field	Type	Description
tid	string	Unique webhook identifier
name	string	Webhook name
url	string	Webhook URL slug — use this in external services
message	string	Message template
is_active	boolean	Whether webhook is active

{
  "tid": "kblf7mh9j8jjyeh4fx",
  "name": "GitHub Push",
  "url": "cs994rqfkk8ljngt",
  "message": "Push to %repository.name%: %head_commit.message%",
  "application_tid": "qm47b9pzxzx7applfd0",
  "device_tid": "",
  "is_active": true,
  "created_at": "01.09.2023 22:38:48"
}

Using Your Webhook

Configure your external service to POST to:

https://api.pocketalert.app/v1/webhooks/receive/{url}

Error Responses

Status	Description
401	Unauthorized — Invalid or missing token
422	Validation Error — Missing required fields