DRAFTThe sandbox is not live yet. Every example here was returned by the platform's code in a test run on 2026-10-28, priced with example fees: no fee amount in them is an SMP price. Paths and fields can change before launch. Live keys are issued only after our bank program is approved.Sandbox not live yet · examples from a test run on 2026-10-28 · example fees

Reference · 5 operations

Webhooks

Subscribe an HTTPS endpoint to signed events, and send it a signed test event.

Sandboxhttps://sandbox.socialmatterspay.com
Livehttps://api.socialmatterspay.com
GET /v1/webhooks

List subscriptions
Secret key

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

Responses

StatusMeaning
200Subscriptions

Fields of each item of data (200)

FieldNotes
idstring—
objectstring = "webhook_subscription"—
urlstring—
eventsarray of string—
activeboolean—
site_idstring | nullSet: hears only that site's payments; null: the whole merchant
created_atstring (date-time)—
Example

List subscriptions

GET /v1/webhooks
curl https://sandbox.socialmatterspay.com/v1/webhooks \
  -H 'Authorization: Bearer sk_sandbox_…'
Response · 200
HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "a4602568-d7c4-46ee-9f8b-b7d99c853837",
      "object": "webhook_subscription",
      "url": "https://northwind.example/smp/webhooks",
      "events": [
        "payment.authorized",
        "payment.settled",
        … 6 more
      ],
      "active": true,
      "site_id": null,
      "created_at": "2026-10-28T00:22:34.449Z"
    }
  ]
}
POST /v1/webhooks

Subscribe an HTTPS URL to events
Secret key

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

The signing secret is returned once, here.

Request body

FieldNotes
url requiredstring (uri)pattern ^https://
site_idstringOnly this site's payments (a site's key sets its own)
events requiredarray of enumone of payment.authorized, payment.declined, payment.settled, payment.released, payment.returned, payment.voided, payment.refunded, payout.initiated, payout.settled, payout.failed, fee.assessed, invoice.paid, invoice.partially_paid, invoice.overdue, bank_account.disconnected, bank_account.relink_required, bank_account.relink_recommended, bank_account.owner_changed, *. at least 1 item

Responses

StatusMeaning
201Subscription created
400Error — error shape and codes
409Error — error shape and codes

Fields of data (201)

FieldNotes
idstring—
objectstring = "webhook_subscription"—
urlstring—
eventsarray of string—
activeboolean—
site_idstring | nullSet: hears only that site's payments; null: the whole merchant
created_atstring (date-time)—
secretstringpattern ^whsec_[a-f0-9]{64}$
Examples (2)

Subscribe to events

POST /v1/webhooks
curl -X POST https://sandbox.socialmatterspay.com/v1/webhooks \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://northwind.example/smp/webhooks",
  "events": [
    "payment.authorized",
    "payment.settled",
    "payment.released",
    "payment.declined",
    "payment.returned",
    "payout.initiated",
    "payout.settled",
    "fee.assessed"
  ]
}'
Response · 201
HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "a4602568-d7c4-46ee-9f8b-b7d99c853837",
    "object": "webhook_subscription",
    "url": "https://northwind.example/smp/webhooks",
    "events": [
      "payment.authorized",
      "payment.settled",
      … 6 more
    ],
    "active": true,
    "site_id": null,
    "secret": "whsec_…",
    "created_at": "2026-10-28T00:22:34.449Z"
  }
}

Subscribe to invoice events

POST /v1/webhooks
curl -X POST https://sandbox.socialmatterspay.com/v1/webhooks \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://northwind.example/smp/webhooks",
  "events": [
    "invoice.paid",
    "invoice.partially_paid",
    "invoice.overdue"
  ]
}'
Response · 201
HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "6fe5437f-652d-460a-a897-14dc0412cd11",
    "object": "webhook_subscription",
    "url": "https://northwind.example/smp/webhooks",
    "events": [
      "invoice.paid",
      "invoice.partially_paid",
      "invoice.overdue"
    ],
    "active": true,
    "site_id": null,
    "secret": "whsec_…",
    "created_at": "2026-10-28T00:22:38.658Z"
  }
}
GET /v1/webhooks/{id}

Get a subscription
Secret key

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

Parameters

FieldNotes
id requiredpath · string—

Responses

StatusMeaning
200Subscription
404Error — error shape and codes

Fields of data (200)

FieldNotes
idstring—
objectstring = "webhook_subscription"—
urlstring—
eventsarray of string—
activeboolean—
site_idstring | nullSet: hears only that site's payments; null: the whole merchant
created_atstring (date-time)—
Example

Get a subscription

GET /v1/webhooks/a4602568-d7c4-46ee-9f8b-b7d99c853837
curl https://sandbox.socialmatterspay.com/v1/webhooks/a4602568-d7c4-46ee-9f8b-b7d99c853837 \
  -H 'Authorization: Bearer sk_sandbox_…'
Response · 200
HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "a4602568-d7c4-46ee-9f8b-b7d99c853837",
    "object": "webhook_subscription",
    "url": "https://northwind.example/smp/webhooks",
    "events": [
      "payment.authorized",
      "payment.settled",
      … 6 more
    ],
    "active": true,
    "site_id": null,
    "created_at": "2026-10-28T00:22:34.449Z"
  }
}
DELETE /v1/webhooks/{id}

Deactivate a subscription
Secret key

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

Parameters

FieldNotes
id requiredpath · string—

Responses

StatusMeaning
200Deactivated
404Error — error shape and codes

Fields of data (200)

FieldNotes
idstring—
objectstring = "webhook_subscription"—
urlstring—
eventsarray of string—
activeboolean—
site_idstring | nullSet: hears only that site's payments; null: the whole merchant
created_atstring (date-time)—
Example

Turn off a subscription

DELETE /v1/webhooks/a4602568-d7c4-46ee-9f8b-b7d99c853837
curl -X DELETE https://sandbox.socialmatterspay.com/v1/webhooks/a4602568-d7c4-46ee-9f8b-b7d99c853837 \
  -H 'Authorization: Bearer sk_sandbox_…'
Response · 200
HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "a4602568-d7c4-46ee-9f8b-b7d99c853837",
    "object": "webhook_subscription",
    "active": false
  }
}
POST /v1/webhooks/{id}/test

Queue a signed webhook.test delivery to this subscription
Secret key

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

Parameters

FieldNotes
id requiredpath · string—

Responses

StatusMeaning
202Queued
404Error — error shape and codes

Fields of data (202)

FieldNotes
delivery_idstring—
eventstring = "webhook.test"—
statusstring = "queued"—
Example

Send a signed test event

POST /v1/webhooks/a4602568-d7c4-46ee-9f8b-b7d99c853837/test
curl -X POST https://sandbox.socialmatterspay.com/v1/webhooks/a4602568-d7c4-46ee-9f8b-b7d99c853837/test \
  -H 'Authorization: Bearer sk_sandbox_…'
Response · 202
HTTP 202
Cache-Control: no-store

{
  "data": {
    "delivery_id": "8c493ec5-8fc9-4e01-babb-311563005fc6",
    "event": "webhook.test",
    "status": "queued"
  }
}