API Guide

Webhooks API

Endpoint reference for developer webhook management plus partner webhook subscriptions, tests, and delivery event logs.

Start with getting started Explore API docs

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 JWT
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.

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, 503.

POST /api/developer/webhook

List or create developer webhook endpoints from the developer console.

Auth: Account Bearer JWT
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.

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, 503.

GET /api/developer/webhook/:id/secret

Return the signing secret for a developer webhook.

Auth: Account Bearer JWT
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.

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, 503.

POST /api/developer/webhook/:id/test

Send a developer webhook test event.

Auth: Account Bearer JWT
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.

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, 503.

DELETE /api/developer/webhook/:id

Delete a developer webhook endpoint.

Auth: Account Bearer JWT
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.

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, 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. External seller payments remain outside SoundSync managed-checkout processing coverage.

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.

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, 500.

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: 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, 500.

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: 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, 500.

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. External seller payments remain outside SoundSync managed-checkout processing coverage.

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.