# Webhook events

What Packlets sends to your webhook URL: events, headers, signature and retries.

When you do something in the app, Packlets sends an event to your packlet's webhook URL. This page is for looking things up. How to build a receiver is covered under [Set up a webhook](https://packlets.app/en/docs/webhook.md).

## Overview

| `type` | `X-Packlets-Event` | When |
|---|---|---|
| [`button`](#button-tapped-button) | `button.pressed` | You tap an action [button](https://packlets.app/en/docs/knoepfe.md) under a message. |
| [`ui`](#element-used-ui) | `ui.changed` | You use an [element](https://packlets.app/en/docs/elemente.md) in a message: button, toggle or input field. |
| [`message`](#chat-message-message) | `message.created` | You write in a [channel with replies](https://packlets.app/en/docs/chat.md). |

Every event is a `POST` with a JSON body. `type`, `packlet_id`, `event_id` and `timestamp` are always included. All times are ISO 8601 in UTC, only `timestamp` is a number.

| Field | Meaning |
|---|---|
| `event_id` | Identifier of the event. If Packlets retries delivery, it stays the same. |
| `timestamp` | Time of delivery in seconds since 1970 (Unix time). |

Both are in the body and are therefore covered by the [signature](#signature). With them you can detect [repeated and old requests](#replay-protection).

## Button tapped: button

```json
{
  "type": "button",
  "packlet_id": "9d2f7c10-3a5b-4c8e-9f21-6b7d8e9f0a12",
  "message_id": "5b0c1a52-7c1e-4a43-9d0b-2f6f0c7d1e11",
  "button_id": "done",
  "pressed_at": "2026-11-09T18:00:00.000Z"
}
```

| Field | Meaning |
|---|---|
| `message_id` | The message the button belongs to. The same value as in the response of `POST /v1/push`. |
| `button_id` | The `id` you gave the button. |
| `pressed_at` | Time of the tap. |

This event arrives at most once per message: after the first tap, the message's action buttons are done. Link buttons (with `url`) don't trigger an event.

## Element used: ui

```json
{
  "type": "ui",
  "packlet_id": "9d2f7c10-3a5b-4c8e-9f21-6b7d8e9f0a12",
  "message_id": "5b0c1a52-7c1e-4a43-9d0b-2f6f0c7d1e11",
  "element_id": "rollback",
  "value": null,
  "changed_at": "2026-11-10T18:00:00.000Z"
}
```

| Field | Meaning |
|---|---|
| `message_id` | The message the element belongs to. The same value as in the response of `POST /v1/push`. |
| `element_id` | The `id` of the element. |
| `value` | The new value: `true` or `false` for a toggle, the text for an input field, `null` for a button. |
| `changed_at` | Time of the interaction. |

Packlets has already saved the new value. Your tool doesn't have to send it back.

## Chat message: message

```json
{
  "type": "message",
  "packlet_id": "9d2f7c10-3a5b-4c8e-9f21-6b7d8e9f0a12",
  "message_id": "c41e8a77-0d1f-4e6a-b2c3-91a4d5e6f708",
  "text": "Is the shop back up?",
  "sent_at": "2026-11-10T08:15:00.000Z"
}
```

| Field | Meaning |
|---|---|
| `message_id` | Your message. |
| `text` | What you wrote, 1 to 4,000 characters, without formatting. |
| `sent_at` | Time. |

## Headers

| Header | Value |
|---|---|
| `Content-Type` | `application/json` |
| `X-Packlets-Event` | `button.pressed`, `ui.changed` or `message.created` |
| `X-Packlets-Signature` | `sha256=` followed by the signature as hex text |
| `X-Packlets-Event-Id` | The same as `event_id` in the body |
| `X-Packlets-Timestamp` | The same as `timestamp` in the body |
| `User-Agent` | `Packlets-Webhook/1.0` |

## Signature

```text
X-Packlets-Signature = "sha256=" + hex( HMAC-SHA256( secret, body ) )
secret           = hex( SHA-256( PACKLETS_KEY ) )
```

- **Body** is the raw bytes of the request, exactly as they arrive. Not re-serialized JSON.
- **Secret** is the SHA-256 hash of your key as lowercase hex text, 64 characters. This text is the HMAC key, not the 32 bytes behind it.
- If you generate a new key in the app, the secret changes too.

Ready-made code is under [Set up a webhook](https://packlets.app/en/docs/webhook.md#4-verify-the-signature).

## Replay protection

A valid request stays valid even if someone records it and sends it again later. If your tool triggers something that must not happen twice, check two things after the signature:

- **`timestamp`** is at most 5 minutes old. Reject older requests.
- **`event_id`** hasn't been seen by you in those 5 minutes. Otherwise respond with `200` and do nothing.

Read both values from the body, not from the headers: only the body is signed.

## Delivery

| Rule | Value |
|---|---|
| Time limit | 10 seconds until your response |
| Time budget | 30 seconds of response time per minute and account. Once it's used up, Packlets delays further events by a few seconds. So respond right away and do the work afterwards. |
| Success | any `2xx` status. The content of your response isn't read. |
| Retried | no connection, timeout, `429`, `5xx` |
| Not retried | all other responses, including `3xx`. Packlets doesn't follow redirects. |
| Retries | up to 5, so at most 6 attempts |
| Spacing | first about 10 to 20 seconds, then twice as long each time. After around ten minutes Packlets gives up. |

- **At least once:** Because of retries, the same event can arrive several times. It then carries the same `event_id`. How to detect duplicates is covered under [Set up a webhook](https://packlets.app/en/docs/webhook.md#duplicate-events).
- **No catching up:** If the packlet has no webhook URL, nothing is sent and nothing is delivered later either.
- The app shows every attempt in the packlet's activity log, with the status of your response.

## The webhook URL

| Rule | |
|---|---|
| Protocol | `https://` only |
| Length | up to 2,048 characters |
| Credentials in the address | not allowed (`https://name:password@…`) |
| Target | publicly reachable. Packlets rejects private addresses like `localhost`, `10.…`, `192.168.…`. |
