Customer Webhooks

Instead of polling a mailbox, you can have the platform push withdrawal PIN notifications straight to your backend. Register a webhook URL and optional auth headers here. The webhook config rides alongside the customer's email-poller record, so a customer has one webhook target.

Authentication: every endpoint on this page uses a Bearer token in the Authorization header.

Authorization: Bearer YOUR_SESSION_TOKEN

Configure Webhook

POSThttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id/webhooks

Set the webhook URL and, optionally, auth headers sent with every notification. Calling this again overwrites the existing config.

Request Body

Field	Type	Required	Description
url	string	Yes	HTTPS (or HTTP) URL to receive PIN notifications.
headers	array	No	Headers attached to every webhook request (see below).

`headers[]` object

Field	Type	Required	Description
key	string	Yes	Header name. Alphanumeric, hyphens, and underscores only.
value	string	Yes	Header value.

{
  "url": "https://your-domain.com/webhook/pin-notification",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-API-Key", "value": "secret-key" }
  ]
}

Success Response (201 Created):

{
  "success": true,
  "data": {
    "message": "Webhook configured successfully",
    "url": "https://your-domain.com/webhook/pin-notification"
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/webhooks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -d '{
    "url": "https://your-domain.com/webhook/pin-notification",
    "headers": [
      { "key": "Authorization", "value": "Bearer token123" },
      { "key": "X-API-Key", "value": "secret-key" }
    ]
  }'

Errors: 400 invalid URL or header key · 401 invalid token · 404 customer not found · 422 validation failed · 500 server error.

Get Webhook

GEThttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id/webhooks

Retrieve the configured webhook. Header values are masked—you see which headers are set, but not their secrets. Returns 404 if no webhook is configured.

GET https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/webhooks

Success Response (200 OK):

{
  "success": true,
  "data": {
    "url": "https://your-domain.com/webhook/pin-notification",
    "headers": [
      { "key": "Authorization", "value": "***masked***" },
      { "key": "X-API-Key", "value": "***masked***" }
    ]
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/webhooks" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Errors: 401 invalid token · 404 customer or webhook not configured · 500 server error.

Update Webhook

PUThttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id/webhooks

Update the webhook configuration. The body is the same as Configure Webhook: url is required on every call, headers is optional.

{
  "url": "https://your-domain.com/webhook/v2/pin-notification",
  "headers": [
    { "key": "X-API-Key", "value": "rotated-secret-key" }
  ]
}

Success Response (200 OK):

{
  "success": true,
  "data": {
    "message": "Webhook updated successfully",
    "url": "https://your-domain.com/webhook/v2/pin-notification"
  },
  "meta": {
    "timestamp": "2026-01-15T12:00:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X PUT "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/webhooks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -d '{
    "url": "https://your-domain.com/webhook/v2/pin-notification",
    "headers": [
      { "key": "X-API-Key", "value": "rotated-secret-key" }
    ]
  }'

Errors: 400 invalid URL or header key · 401 invalid token · 404 customer not found · 422 validation failed · 500 server error.

Delete Webhook

DELETEhttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id/webhooks

Remove the webhook URL and auth headers. PIN notifications stop being pushed.

DELETE https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/webhooks

Success Response (204 No Content) — empty body, no JSON.

curl -X DELETE "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/webhooks" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Errors: 401 invalid token · 404 customer not found · 500 server error.

Verify Webhook

POSThttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id/webhooks/verify

Send a test payload to the configured URL and report the result. Pass the customer_id in the path—no body.

POST https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/webhooks/verify

Success Response (200 OK) — always 200; the outcome lives in data.message.

Field	Type	Description
message	string	Detail of the test result.
response_data	any	(Optional) Body your webhook returned on failure.

{
  "success": true,
  "data": {
    "message": "Webhook test successful"
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/webhooks/verify" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"