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 old surge-signature header used the format t=<timestamp>,v1=<hex> with its own signed-payload composition, while webhook-signature signs {webhook-id}.{webhook-timestamp}.{raw-body} and uses the v1,<signature> format. If you compute the signature yourself, you need to update both which header you read and how you compute the signature — not just the header name. How to migrate: Update your webhook handler to read webhook-signature instead of surge-signature and to read the webhook-id and webhook-timestamp headers and compute the new signed-payload string.

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

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

See Signature Verification for the full algorithm and per-language examples. If you’re using the standardwebhooks library, no code change is needed. It reads the correct headers and computes the new signature format 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:

from surge import Surge

surge = Surge()
response = surge.users.create_token(user_id="{user_id}")
token = response.token

import Surge from "@surgeapi/node";

const surge = new Surge();
const response = await surge.users.createToken("{user_id}");
const token = response.token;

require "surge_api"

surge = SurgeAPI::Client.new
response = surge.users.create_token("{user_id}")
token = response.token

client = Surge.Client.new(System.get_env("SURGE_API_KEY"))
{:ok, token} = Surge.Users.create_token(client, "{user_id}", %{})

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.

Compliance

Reference

Deprecation Notices

`surge-signature` webhook header

`link.followed.message_id` field

Publishable tokens for embedded components

​surge-signature webhook header

​link.followed.message_id field

​Publishable tokens for embedded components

`surge-signature` webhook header

`link.followed.message_id` field

Publishable tokens for embedded components