API Reference

Webhooks API

Verified partner webhook subscriptions, events, delivery signatures, delivery logs, retry behavior, and Node.js signature verification example.

Start with getting started Explore API docs

POST /activateGET /validatePOST /deactivate

Product credentials
Activation request
Entitlement check
Device registration
Periodic validation
Deactivation when needed

SoundSync

Verified partner webhook endpoints

These endpoints require webhooks:read or webhooks:write partner API scopes.

GET /api/partner/v1/webhooks

List partner webhook subscriptions.

Auth: Scoped partner API key.
Scope: Public, customer-token, developer-user, or scoped partner API surface as noted.
Request fields: partner API key
webhooks:read scope
Returns: webhooks[].
Side effects: None for GET endpoints unless noted.

POST /api/partner/v1/webhooks

Create a partner webhook subscription.

Auth: Scoped partner API key.
Scope: Public, customer-token, developer-user, or scoped partner API surface as noted.
Request fields: partner API key
webhooks:write scope
url
events[]
description optional
Returns: 201 webhook plus one-time signing secret.
Side effects: Stores webhook subscription and generated signing secret. Secret is shown once.

PATCH /api/partner/v1/webhooks/:webhookId

Update partner webhook subscription status/events/url/description or rotate secret when requested.

Auth: Scoped partner API key.
Scope: Public, customer-token, developer-user, or scoped partner API surface as noted.
Request fields: partner API key
webhooks:write scope
webhookId
rotate_secret/rotateSecret optional
Returns: webhook; includes secret only when rotation was requested.
Side effects: May rotate the webhook secret.

DELETE /api/partner/v1/webhooks/:webhookId

Disable a partner webhook subscription.

Auth: Scoped partner API key.
Scope: Public, customer-token, developer-user, or scoped partner API surface as noted.
Request fields: partner API key
webhooks:write scope
webhookId
Returns: Disabled webhook response.
Side effects: Marks subscription disabled.

POST /api/partner/v1/webhooks/test

Queue a partner webhook.test delivery.

Auth: Scoped partner API key.
Scope: Public, customer-token, developer-user, or scoped partner API surface as noted.
Request fields: partner API key
webhooks:write scope
message optional
Returns: success true and event { type webhook.test, id, relationship_id, partner_id, developer_id, created_at }.
Side effects: Queues webhook.test delivery.

GET /api/partner/v1/webhook-events

List partner webhook delivery attempts/events.

Auth: Scoped partner API key.
Scope: Public, customer-token, developer-user, or scoped partner API surface as noted.
Request fields: partner API key
webhooks:read scope
pagination/filter query
Returns: events[] with type/event_id/status/attempt_count/next_attempt_at/last_status_code/last_error/response_preview.
Side effects: None for GET endpoints unless noted.

SoundSync

Verified partner webhook event types

Only events accepted by normalizeWebhookEvents are listed.

Event	When it is used
order.fulfilled	Queued when partner external order fulfillment succeeds.
order.refunded	Supported subscription event type for partner webhook subscriptions.
license.revoked	Supported event type for partner license revocation.
relationship.requested	Supported relationship lifecycle event.
relationship.updated	Supported relationship lifecycle event.
webhook.test	Queued by partner webhook test endpoints.

SoundSync

Node.js signature verification

Partner webhook delivery signs the exact JSON body with HMAC-SHA256 and sends X-SoundSync-Signature: sha256=<hex>. The current partner implementation does not include a timestamp header, so timestamp tolerance must not be claimed as implemented.

Node.js

const crypto = require('crypto');

function verifySoundSyncPartnerWebhook({ rawBody, signatureHeader, secret }) {
  const supplied = String(signatureHeader || '').replace(/^sha256=/, '');
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const suppliedBuffer = Buffer.from(supplied, 'hex');
  const expectedBuffer = Buffer.from(expected, 'hex');
  return suppliedBuffer.length === expectedBuffer.length
    && crypto.timingSafeEqual(suppliedBuffer, expectedBuffer);
}

Delivery behavior

The delivery worker posts JSON with User-Agent SoundSync-Partner-Webhooks/1.0, X-SoundSync-Event, X-SoundSync-Event-Id, and X-SoundSync-Signature. 2xx responses are success via response.ok; failures are retried by queued/failed delivery attempts with next_attempt_at and attempt_count.

API reference

Endpoint groups are organized by authentication model, product scope, request shape, response shape, errors, idempotency, and integration surface.

GET/POST/PATCH/DELETE

Webhooks API

/docs/api/webhooks

Partner webhook subscriptions, delivery events, and signatures.