Reference

Webhook events

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

Open as Markdown

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

typeX-Packlets-EventWhen
buttonbutton.pressedYou tap an action button under a message.
uiui.changedYou use an element in a message: button, toggle or input field.
messagemessage.createdYou 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.

FieldMeaning
event_idIdentifier of the event. If Packlets retries delivery, it stays the same.
timestampTime 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

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"
}
FieldMeaning
message_idThe message the button belongs to. The same value as in the response of POST /v1/push.
button_idThe id you gave the button.
pressed_atTime 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"
}
FieldMeaning
message_idThe message the element belongs to. The same value as in the response of POST /v1/push.
element_idThe id of the element.
valueThe new value: true or false for a toggle, the text for an input field, null for a button.
changed_atTime 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"
}
FieldMeaning
message_idYour message.
textWhat you wrote, 1 to 4,000 characters, without formatting.
sent_atTime.

Headers

HeaderValue
Content-Typeapplication/json
X-Packlets-Eventbutton.pressed, ui.changed or message.created
X-Packlets-Signaturesha256= followed by the signature as hex text
X-Packlets-Event-IdThe same as event_id in the body
X-Packlets-TimestampThe same as timestamp in the body
User-AgentPacklets-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.

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

RuleValue
Time limit10 seconds until your response
Time budget30 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.
Successany 2xx status. The content of your response isn't read.
Retriedno connection, timeout, 429, 5xx
Not retriedall other responses, including 3xx. Packlets doesn't follow redirects.
Retriesup to 5, so at most 6 attempts
Spacingfirst 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
Protocolhttps:// only
Lengthup to 2,048 characters
Credentials in the addressnot allowed (https://name:password@…)
Targetpublicly reachable. Packlets rejects private addresses like localhost, 10.…, 192.168.….