Skip to content
SoundSyncAudio software platform

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.

GET /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.

POST /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.

GET /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.

POST /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.

DELETE /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.

GET /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.

POST /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.

PATCH /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.

DELETE /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.

POST /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.

POST /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.

GET /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.

PracticeWhy it matters
Verify signing secretConfirms the event came from the configured SoundSync webhook.
Store processed event idsPrevents duplicate fulfillment if a webhook is retried.
Return fast 2xx responsesKeeps delivery healthy while heavier work runs in your system.
Use test endpointsConfirms 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.