POST/v1/webhooks

Create a webhook

Registers a URL and subscribes it to one or more event types.

Required scope: webhooks.manageRate limit: 10 rps

The signing secret is returned exactly once, in this call's response — store it immediately. SamaPrime only ever keeps an encrypted copy.

Parameters

urlstringrequired

HTTPS delivery URL.

eventsstring[]required

Array of event types to subscribe to — see Events reference.

Code samples

curl -X POST "https://samaprime.com/api/v1/webhooks" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://merchant.example/callbacks/salamcash","events":["order.completed"]}'

Response

→ 201
{
  "data": {
    "id": "cm_wh_01J8Z9A1BBCCDD",
    "url": "https://merchant.example/webhooks/samaprime",
    "events": [
      "order.completed",
      "order.failed"
    ],
    "secret": "whsec_3f9a2b7c1e0d4a6f8b5c2d1e9f0a7b3c",
    "active": true
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-06T12:00:00Z"
  }
}

Errors

Status	Code
400	`validation_failed` Body must be { url: string, events: string[] }.
400	`invalid_event_type` One or more event types aren't recognized — see Events reference.
400	`insecure_url` The URL must be https:// (loopback http:// is allowed only for local testing).