Surge home page
SupportDashboard
Surge

Deprecation Notices

This page tracks API and SDK features that are deprecated and will be removed in a future version.

surge-signature webhook header

Status: Deprecated — use webhook-signature

What changed: The webhook request signature header was renamed from surge-signature to webhook-signature to align with the Standard Webhooks specification. The signature algorithm (HMAC-SHA256) and the signing secret are unchanged.

How to migrate: Update your webhook handler to read webhook-signature instead of surge-signature:

# Before
signature = request.headers.get("surge-signature")

# After
signature = request.headers.get("webhook-signature")

If you're using the standardwebhooks library, no code change is needed — it reads the correct header automatically.

Timeline: Both headers are currently sent on all webhook requests. The surge-signature header will be removed in a future release. Migrate before then to avoid broken signature verification.

link.followed.message_id field

Status: Deprecated — use data.message.id

What changed: The link.followed webhook event originally included a top-level message_id field. This has been replaced by a nested message object that contains id and additional message metadata.

How to migrate:

# Before
message_id = payload["message_id"]

# After
message_id = payload["data"]["message"]["id"]

Timeline: The top-level message_id field is still included in link.followed events for backward compatibility. It will be removed in a future release.

Publishable tokens for embedded components

Status: Deprecated — use signed JWT authentication

What changed: Embedded UI components (Inbox, Conversation, Unread Count) previously supported a "publishable token" authentication method. This has been replaced by signed JWT authentication, which provides stronger security and token expiration control.

How to migrate: Generate a JWT using the token endpoint:

curl -X POST https://api.surge.app/users/USER_ID/tokens \
  -H "Authorization: Bearer YOUR_API_KEY"

Use the returned token value when mounting embedded components. See Embeddable UI Components for the full authentication documentation.

Timeline: Publishable tokens will stop working in a future release. Migrate all embedded component mounts to JWT authentication.