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:

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"

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.