# Webhook Settings

Learn how to configure webhook message templates to extract data from incoming JSON payloads.

## Message Template Syntax

When creating a webhook, you define a message template that determines how incoming JSON data is formatted into notifications.

### Basic Patterns

| Pattern | Description |
|---------|-------------|
| `*` | Output the entire JSON payload |
| `%field%` | Extract a top-level field |
| `%object.field%` | Extract a nested field |
| `%array.0%` | Get first element of an array |
| `%array.0.field%` | Get a field from array element |

## Examples

### Example JSON Payload

Consider this incoming webhook payload:

```json
{
  "event": {
    "title": "New Order",
    "message": "A new order has been placed with ID 12345",
    "tags": ["order", "new"],
    "users": [
      {"first": "Dale", "last": "Murphy", "age": 44, "nets": ["ig", "fb", "tw"]},
      {"first": "Roger", "last": "Craig", "age": 68, "nets": ["fb", "tw"]},
      {"first": "Jane", "last": "Murphy", "age": 47, "nets": ["ig", "tw"]}
    ]
  }
}
```

### Template Configuration

**Full JSON**

```text
*
```

**Extracted Fields**

```text
Title: %event.title%
Message: %event.message%
Tags: %event.tags%
Users: %event.users.0%
First user: %event.users.0.first% %event.users.0.last%
```

### Output Result

```
Title: New Order
Message: A new order has been placed with ID 12345
Tags: ["order","new"]
Users: {"age":44,"first":"Dale","last":"Murphy","nets":["ig","fb","tw"]}
First user: Dale Murphy
```

## Common Integrations

### GitHub Webhooks

```text
🔔 %action%: %repository.full_name%
%sender.login%: %commits.0.message%
```

### Sentry Error Tracking

```text
🚨 %project_name%: %message%
Level: %level%
URL: %url%
```

### Grafana Alerts

```text
⚠️ %state%: %title%

%message%

Status: %status%
```

### Uptime Robot

```text
🔴 %monitorFriendlyName%
Status: %alertTypeFriendlyName%
Details: %alertDetails%
```

## Advanced Path Syntax

For complex JSON extraction, we use [GJSON Path Syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md).

### Useful Patterns

| Pattern | Description |
|---------|-------------|
| `%users.#%` | Count of array items |
| `%users.#.first%` | Array of all `first` values |
| `%users.@reverse%` | Reverse array order |
| `%data.@pretty%` | Pretty-print JSON |

> **Tip: Learn More**
>
> Full documentation: [GJSON Path Syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)

## Priority Level

Incoming payloads may carry a `level` field to control how the push is delivered — a name (`silent`, `low`, `default`, `high`, `critical`) or an int (`-2`..`2`). See [Message priority levels](https://info.pocketalert.app/api/messages/create.md#priority-levels).

Resolution order (first match wins):

1. The `level` field in the incoming JSON payload
2. The webhook's `default_level` (set when creating the webhook)
3. The application's default level
4. `default` (normal)

Unlike the direct API, webhook input is lenient: an unrecognized `level` value is ignored (falling back to the defaults) rather than rejected, so alerts are never dropped.

## Action Buttons

A webhook can attach up to 3 action buttons to every notification it generates. Set the `actions` field (a JSON string) when creating or updating the webhook — see [Create Webhook → Action Buttons Template](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template).

`label` and `value` support the same `%field.path%` placeholders as the message template, so buttons can be built from the incoming payload:

```json
[
  { "type": "view", "label": "Open PR", "value": "%pull_request.html_url%" },
  { "type": "http", "label": "Merge", "value": "{\"url\":\"https://ci.example.com/merge/%pull_request.number%\",\"method\":\"POST\"}" }
]
```

After substitution the array is validated (max 3, `type` ∈ `view`/`http`/`copy`, `http` requires a `url`). Like level parsing, this is lenient: invalid actions are dropped and the notification is still delivered.

After creating a webhook, you can test it:

**cURL**

```bash
curl -X POST "https://api.pocketalert.app/v1/webhooks/receive/YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"event": {"title": "Test", "message": "Hello World"}}'
```

**JavaScript**

```javascript
await fetch('https://api.pocketalert.app/v1/webhooks/receive/YOUR_WEBHOOK_URL', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    event: { title: 'Test', message: 'Hello World' }
  })
});
```

**Python**

```python
import requests

requests.post(
    'https://api.pocketalert.app/v1/webhooks/receive/YOUR_WEBHOOK_URL',
    json={'event': {'title': 'Test', 'message': 'Hello World'}}
)
```

**PHP**

```php
Http::post('https://api.pocketalert.app/v1/webhooks/receive/YOUR_WEBHOOK_URL', [
    'event' => [
        'title' => 'Test',
        'message' => 'Hello World',
    ],
]);
```

This will send a test notification to your devices using your configured message template.