Set webhook configuration

PUT

/v1/webhook

curl --request PUT \
  --url https://api.sulpayments.ch/v1/webhook \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "webhook_secret": "example", "webhook_url": "example" }'

• Production
• Sandbox

Configures where settlement-completed notifications are POSTed for the authenticated merchant, and the secret they are signed with. A null or empty webhook_url clears the endpoint. The URL must be a public https(s) address (internal/loopback/metadata hosts are rejected). The secret is required the first time a URL is set; a later URL change may omit it to keep the current secret.

Authorizations

• api_key

Request Body^required

Media typeapplication/json

What a merchant sends to configure its webhook. A null/empty url clears the endpoint (and retires the secret with it). The secret is chosen by the merchant — it must know it to verify the signatures — and is required the first time a url is set; a later url change may omit it to keep the current one.

object

webhook_secret

string | null

webhook_url

string | null

Example^generated

{
  "webhook_secret": "example",
  "webhook_url": "example"
}

Responses

200

Updated configuration

Media typeapplication/json

A merchant's own webhook configuration, as it sees it. The secret is never returned — only whether one is set.

object

webhook_secret_set

required

boolean

webhook_url

string | null

Example^generated

{
  "webhook_secret_set": true,
  "webhook_url": "example"
}

400

Invalid URL or missing secret

Media typeapplication/json

The error envelope every 4xx/5xx response uses. The error.code is machine-stable across locales; error.message is localized via the request's Accept-Language (en by default). error.fields is present only for per-field validation failures.

object

error

required

The body of an [ErrorEnvelope].

object

code

required

Machine-stable error code (stable across locales).

string

Allowed values: invalid_credentials unauthenticated origin_not_allowed challenge_failed locked invalid_link invalid_code otp_enforced no_merchant no_partner not_found invalid_body internal_error provider_unavailable provider_call_failed quote_refused conversion_refused payout_refused payout_wallet_out_of_gas unexpected_failure provider_still_processing database_grant_missing rail_inactive fx_accounts_missing sender_not_registered payout_outcome_unknown conversion_outcome_unknown validation_failed webhook_endpoint_not_configured access_token_missing access_token_malformed access_token_invalid access_verification_unavailable conflict admin_validation_failed forbidden issuance_not_enabled merchant_identity_incomplete issuance_quota_exceeded issuance_rate_limited end_user_reference_exists currency_not_enabled currency_not_supported required invalid_url unsafe_url unresolvable_host

fields

Per-field validation errors, present only for validation_failed.

Array<object> | null

One field-level validation failure inside [ApiError::fields].

object

code

required

The machine-stable reason code for this field.

string

Allowed values: invalid_credentials unauthenticated origin_not_allowed challenge_failed locked invalid_link invalid_code otp_enforced no_merchant no_partner not_found invalid_body internal_error provider_unavailable provider_call_failed quote_refused conversion_refused payout_refused payout_wallet_out_of_gas unexpected_failure provider_still_processing database_grant_missing rail_inactive fx_accounts_missing sender_not_registered payout_outcome_unknown conversion_outcome_unknown validation_failed webhook_endpoint_not_configured access_token_missing access_token_malformed access_token_invalid access_verification_unavailable conflict admin_validation_failed forbidden issuance_not_enabled merchant_identity_incomplete issuance_quota_exceeded issuance_rate_limited end_user_reference_exists currency_not_enabled currency_not_supported required invalid_url unsafe_url unresolvable_host

field

required

The request field the error applies to (e.g. webhook_url).

string

message

required

Human-readable message, localized by Accept-Language.

string

Example

{
  "error": {
    "code": "invalid_credentials",
    "fields": [
      {
        "code": "invalid_credentials"
      }
    ],
    "message": "One or more fields are invalid."
  }
}

401

Missing or invalid API key

Media typeapplication/json

The error envelope every 4xx/5xx response uses. The error.code is machine-stable across locales; error.message is localized via the request's Accept-Language (en by default). error.fields is present only for per-field validation failures.

object

error

required

The body of an [ErrorEnvelope].

object

code

required

Machine-stable error code (stable across locales).

string

Allowed values: invalid_credentials unauthenticated origin_not_allowed challenge_failed locked invalid_link invalid_code otp_enforced no_merchant no_partner not_found invalid_body internal_error provider_unavailable provider_call_failed quote_refused conversion_refused payout_refused payout_wallet_out_of_gas unexpected_failure provider_still_processing database_grant_missing rail_inactive fx_accounts_missing sender_not_registered payout_outcome_unknown conversion_outcome_unknown validation_failed webhook_endpoint_not_configured access_token_missing access_token_malformed access_token_invalid access_verification_unavailable conflict admin_validation_failed forbidden issuance_not_enabled merchant_identity_incomplete issuance_quota_exceeded issuance_rate_limited end_user_reference_exists currency_not_enabled currency_not_supported required invalid_url unsafe_url unresolvable_host

fields

Per-field validation errors, present only for validation_failed.

Array<object> | null

One field-level validation failure inside [ApiError::fields].

object

code

required

The machine-stable reason code for this field.

string

Allowed values: invalid_credentials unauthenticated origin_not_allowed challenge_failed locked invalid_link invalid_code otp_enforced no_merchant no_partner not_found invalid_body internal_error provider_unavailable provider_call_failed quote_refused conversion_refused payout_refused payout_wallet_out_of_gas unexpected_failure provider_still_processing database_grant_missing rail_inactive fx_accounts_missing sender_not_registered payout_outcome_unknown conversion_outcome_unknown validation_failed webhook_endpoint_not_configured access_token_missing access_token_malformed access_token_invalid access_verification_unavailable conflict admin_validation_failed forbidden issuance_not_enabled merchant_identity_incomplete issuance_quota_exceeded issuance_rate_limited end_user_reference_exists currency_not_enabled currency_not_supported required invalid_url unsafe_url unresolvable_host

field

required

The request field the error applies to (e.g. webhook_url).

string

message

required

Human-readable message, localized by Accept-Language.

string

Example

{
  "error": {
    "code": "invalid_credentials",
    "fields": [
      {
        "code": "invalid_credentials"
      }
    ],
    "message": "One or more fields are invalid."
  }
}