Reference
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.
Overview
type | X-Packlets-Event | When |
|---|---|---|
button | button.pressed | You tap an action button under a message. |
ui | ui.changed | You use an element in a message: button, toggle or input field. |
message | message.created | You write in a channel with replies. |
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. With them you can detect repeated and old requests.
Button tapped: button
{
"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
{
"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
{
"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
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.
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:
timestampis at most 5 minutes old. Reject older requests.event_idhasn't been seen by you in those 5 minutes. Otherwise respond with200and 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. - 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.…. |