Versions

Each subscription is pinned to a payload version with webhook_version. Blujay renders every event for that subscription in that version’s shape, so your receiver keeps working when new versions ship. New subscriptions use the latest version unless you choose another.

​

Versions

​

The 2026-06-14 shape

On 2026-06-14, a message event’s data has four fields: message_id, chat_id, phone_number_id and status. A message.failed event adds failure_code only when your number was retired (SENDER_RETIRED); other failures have no reason. A message.received event adds contact_id (or sender in a group), text, and a parts list that holds the text only, never media. There is no direction, no service, no timestamps and no failure object. Reaction, typing, group, contact and phone number events have the same shape on every version. If you inherit a subscription on this version, read the message with GET /v1/messages/{message_id} for everything the event leaves out, or upgrade it. Use the latest version for new integrations. Older versions remain supported for existing receivers. There is no sunset policy yet: Blujay will announce one, with notice, before retiring any version.

​

Upgrade a subscription

1. Update your receiver to accept the new fields, and keep it accepting the old shape for a while: events created before the change keep their original shape, including when they are delivered again.
2. Change the version:
   curl -X PATCH https://api.blujay.io/v1/webhook-subscriptions/whsub_abc123 \
     -H "Authorization: Bearer blu_your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"webhook_version": "2026-10-03"}'
   
3. New events use the new version from then on.

Every event says which version it uses in its webhook_version field, so your receiver can handle both shapes during the switch. A version string outside the table is rejected with 400 VALIDATION_ERROR.

​

Limitations

• A version applies to the whole subscription. You can’t pick a version per event type.
• An event keeps the version it was created with. Changing the version never re-renders events that already exist, including on replay.
• Group typing needs 2026-10-03 and a Dedicated number. No version adds group typing for Free Plan numbers; see Plans.

​

Next steps