API Guide
Webhooks API
Endpoint reference for developer webhook management plus partner webhook subscriptions, tests, and delivery event logs.
SoundSync
Developer webhook endpoints
Developer console webhook routes require a signed-in developer account.
/api/developer/webhook
List or create developer webhook endpoints from the developer console.
- Auth
- Account Bearer session token
- Scope
- Product or storefront scoped
- Returns
- Webhook list or created webhook.
- Notes
- Developer webhook permissions and all-products scope apply. Missing storage can return DEVELOPER_WEBHOOKS_UNAVAILABLE for mutations. Public HTTP(S) webhook destinations must not contain URL credentials or resolve to private/reserved addresses. Test delivery pins validated DNS, does not follow redirects and returns at most 500 response characters from a bounded response read. A redirect status is returned for inspection; it is not followed with the webhook secret.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"webhooks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"isActive": {
"type": "boolean"
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastUsedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 500, 501, 502, 504, 503.
/api/developer/webhook
List or create developer webhook endpoints from the developer console.
- Auth
- Account Bearer session token
- Scope
- Product or storefront scoped
- Request fields
- url: string (required)
- Returns
- Webhook list or created webhook.
- Notes
- Stores a developer outbound webhook and returns its signing secret privately. This endpoint reads url, not an arbitrary event list. Public HTTP(S) webhook destinations must not contain URL credentials or resolve to private/reserved addresses. Test delivery pins validated DNS, does not follow redirects and returns at most 500 response characters from a bounded response read. A redirect status is returned for inspection; it is not followed with the webhook secret.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
}
},
"required": [
"url"
],
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"secret": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 500, 501, 502, 504, 503.
/api/developer/webhook/:id/secret
Return the signing secret for a developer webhook.
- Auth
- Account Bearer session token
- Scope
- Product or storefront scoped
- Returns
- Webhook signing secret for the selected endpoint.
- Notes
- Private webhook signing material. Never embed it in a plugin, public page, screenshot or shared log. Public HTTP(S) webhook destinations must not contain URL credentials or resolve to private/reserved addresses. Test delivery pins validated DNS, does not follow redirects and returns at most 500 response characters from a bounded response read. A redirect status is returned for inspection; it is not followed with the webhook secret.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"secret": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 500, 501, 502, 504, 503.
/api/developer/webhook/:id/test
Send a developer webhook test event.
- Auth
- Account Bearer session token
- Scope
- Product or storefront scoped
- Returns
- Webhook test result.
- Notes
- Sends the server-defined synthetic purchase.completed test to the saved destination. No custom request-body test event is read; this makes a real outbound HTTP request. Public HTTP(S) webhook destinations must not contain URL credentials or resolve to private/reserved addresses. Test delivery pins validated DNS, does not follow redirects and returns at most 500 response characters from a bounded response read. A redirect status is returned for inspection; it is not followed with the webhook secret.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"status": {
"type": "integer"
},
"responsePreview": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 500, 501, 502, 504, 503.
/api/developer/webhook/:id
Delete a developer webhook endpoint.
- Auth
- Account Bearer session token
- Scope
- Product or storefront scoped
- Returns
- Deletion result.
- Notes
- Developer webhook permissions and all-products scope apply. Missing storage can return DEVELOPER_WEBHOOKS_UNAVAILABLE for mutations. Public HTTP(S) webhook destinations must not contain URL credentials or resolve to private/reserved addresses. Test delivery pins validated DNS, does not follow redirects and returns at most 500 response characters from a bounded response read. A redirect status is returned for inspection; it is not followed with the webhook secret.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 500, 501, 502, 504, 503.
SoundSync
Partner webhook endpoints
Partner webhook routes require partner API key scopes.
/api/partner/v1/webhooks
List or create partner webhook subscriptions.
- Auth
- Relationship-scoped partner API key
- Scope
- webhooks:read or webhooks:write
- Returns
- Webhook subscription list or created subscription.
- Notes
- Relationship-scoped partner key and operation-specific campaigns/webhooks read or write scope are required. Custom fulfillment webhook writes require SoundSync activation and return 410 PARTNER_FULFILLMENT_DISABLED when disabled. Authorized campaign and historical reads are separate. External seller payments remain outside SoundSync-managed checkout and its sales percentage. External sellers handle their own provider costs; applicable SoundSync service and redemption charges remain separate.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"webhooks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/partner/v1/webhooks
List or create partner webhook subscriptions.
- Auth
- Relationship-scoped partner API key
- Scope
- webhooks:read or webhooks:write
- Request fields
- url: string (required)
- events: array
- description: string
- Returns
- Webhook subscription list or created subscription.
- Notes
- Returns private signing material inside webhook.secret, not a top-level secret. Only url is required: omitted events defaults to order.fulfilled, order.refunded, license.revoked and webhook.test. An explicit event list must retain at least one supported event after normalization. Use public HTTPS without credentials or a nonstandard port. Fulfillment availability and webhook-write scope are required; do not publish a live secret. Disabled custom fulfillment returns 410 PARTNER_FULFILLMENT_DISABLED.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"order.fulfilled",
"order.refunded",
"license.revoked",
"relationship.requested",
"relationship.updated",
"webhook.test"
]
}
},
"description": {
"type": "string"
}
},
"required": [
"url"
],
"additionalProperties": true
}
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"webhook": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string"
},
"secret": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 410, 429, 500, 503.
Operation errors: PARTNER_FULFILLMENT_DISABLED.
/api/partner/v1/webhooks/:webhookId
Update or delete a partner webhook subscription.
- Auth
- Relationship-scoped partner API key
- Scope
- webhooks:write
- Request fields
- url: string
- events: array
- description: string
- rotate_secret: boolean
- status: string
- Returns
- Updated or deleted webhook subscription state.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"description": {
"type": "string"
},
"rotate_secret": {
"type": "boolean"
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"webhook": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"secret": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 403, 404, 409.
/api/partner/v1/webhooks/:webhookId
Update or delete a partner webhook subscription.
- Auth
- Relationship-scoped partner API key
- Scope
- webhooks:write
- Returns
- Updated or deleted webhook subscription state.
- Notes
- Requires custom fulfillment activation; disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED. Disables the subscription rather than implying physical erasure of webhook delivery/audit history.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"deleted": {
"type": "boolean"
},
"id": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 410, 429, 500, 503.
Operation errors: PARTNER_FULFILLMENT_DISABLED.
/api/partner/v1/webhooks/test
Create a test partner webhook event.
- Auth
- Relationship-scoped partner API key
- Scope
- webhooks:write
- Request fields
- message: string
- Returns
- Test event result.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"event": {
"type": "object",
"properties": {
"type": {
"const": "webhook.test"
},
"id": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 403, 404, 409.
/api/partner/v1/webhooks/:webhookId/test
Send a test event through a specific partner webhook.
- Auth
- Relationship-scoped partner API key
- Scope
- webhooks:write
- Request fields
- status: string
- message: string
- Returns
- Test event result.
- Notes
- Requires custom fulfillment activation; disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED. Can update the selected webhook status and queues a synthetic webhook.test event. Queue acceptance is not successful delivery.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"status": {
"type": "string"
},
"message": {
"type": "string"
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"event": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"relationship_id": {
"type": "integer",
"minimum": 1
},
"partner_id": {
"type": "integer",
"minimum": 1
},
"developer_id": {
"type": "integer",
"minimum": 1
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 410, 429, 500, 503.
Operation errors: PARTNER_FULFILLMENT_DISABLED.
/api/partner/v1/webhook-events
List partner webhook delivery events.
- Auth
- Relationship-scoped partner API key
- Scope
- webhooks:read
- Request fields
- query limit: integer
- Returns
- Webhook event log rows.
- Notes
- Relationship-scoped partner key and operation-specific campaigns/webhooks read or write scope are required. Custom fulfillment webhook writes require SoundSync activation and return 410 PARTNER_FULFILLMENT_DISABLED when disabled. Authorized campaign and historical reads are separate. External seller payments remain outside SoundSync-managed checkout and its sales percentage. External sellers handle their own provider costs; applicable SoundSync service and redemption charges remain separate.
Request, response and error reference
Query and header parameters
[
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"type": {
"type": "string"
},
"endpoint": {
"type": "string"
},
"method": {
"type": "string"
},
"request_id": {
"type": [
"string",
"null"
]
},
"idempotency_key": {
"type": [
"string",
"null"
]
},
"external_order_id": {
"type": [
"string",
"null"
]
},
"status_code": {
"type": "integer"
},
"success": {
"type": "boolean"
},
"error_code": {
"type": [
"string",
"null"
]
},
"error_message": {
"type": [
"string",
"null"
]
},
"request_summary": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"response_summary": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"deliveries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"subscription_id": {
"type": [
"integer",
"null"
]
},
"type": {
"type": "string"
},
"event_id": {
"type": "string"
},
"status": {
"type": "string"
},
"attempt_count": {
"type": "integer"
},
"next_attempt_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_attempt_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_status_code": {
"type": "integer"
},
"last_error": {
"type": [
"string",
"null"
]
},
"response_preview": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
SoundSync
Webhook handling
Production webhook consumers should verify signatures, use idempotency on their side, and tolerate retries.
| Practice | Why it matters |
|---|---|
| Verify signing secret | Confirms the event came from the configured SoundSync webhook. |
| Store processed event ids | Prevents duplicate fulfillment if a webhook is retried. |
| Return fast 2xx responses | Keeps delivery healthy while heavier work runs in your system. |
| Use test endpoints | Confirms URL, auth, and event parsing before launch. |
Use a public webhook receiver
Developer webhook setup accepts public HTTP or HTTPS receiver URLs without embedded usernames or passwords. Private, loopback, link-local, mapped private IPv6 and reserved network destinations are rejected. Test requests pin the validated DNS address and do not follow redirects with the webhook secret.
A test returns the receiver HTTP status and at most 500 response characters from a bounded read. A redirect status does not mean its destination was contacted. DNS or delivery failures return a controlled error; an accepted test does not guarantee that your application processed the event. Partner webhook delivery retains its public HTTPS requirement, no-redirect behavior and signed event contract.
