Update channel settings

Patches the STR channel settings. Only the provided fields are updated; absent fields keep their current value. At least one field must be provided. Setting the participant ISPB requires an explicit 8-character value (placeholders such as 00000000 are rejected). Idempotent — replaying the same X-Idempotency key with the same body returns the cached response.

PATCH /v1/str/settings

Update channel settings

cURL

curl --request PATCH \
  --url https://spb.sandbox.lerian.net/v1/str/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "deliveryMode": "WEBHOOK",
  "ispb": "12345678",
  "metadata": {}
}
'

200

{
  "channelStatus": "CONNECTED",
  "correlationId": "req-7a3f9c2e",
  "deliveryMode": "WEBHOOK",
  "ispb": "12345678",
  "webhooks": [
    {
      "createdAt": "2026-05-04T18:30:00Z",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "isActive": true,
      "messageTypes": [
        "STR0004",
        "STR0007"
      ],
      "url": "https://example.com/webhooks/str",
      "metadata": {}
    }
  ],
  "certDaysRemaining": 365,
  "certificateExpiresAt": "2027-05-04T18:30:00Z",
  "metadata": {},
  "readiness": {
    "blockers": [
      "redis: connection refused"
    ],
    "status": "READY",
    "warnings": [
      "certificate expires in 12 days"
    ]
  }
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency · string · required

Idempotency key. Required on every mutation.

X-TTL · string

Idempotency key TTL in seconds (overrides the service default).

Body

application/json

deliveryMode · enum<string>

Optional notification delivery mode to set: WEBHOOK, EVENT (streaming), or BOTH; left unchanged when omitted.

Available options: WEBHOOK, EVENT, BOTH

Example:

"WEBHOOK"

ispb · string

Optional participant ISPB to set, the 8-character BACEN institution identifier; left unchanged when omitted.

Required string length: 8

Pattern: ^[0-9A-Z]{8}$

Example:

"12345678"

metadata · object

Optional client-supplied settings metadata to merge; sensitive keys are redacted on read.

Show child attributes

Response

200

application/json

OK

channelStatus · enum<string> · required

SPB channel connectivity status: CONNECTED or PENDING_CONFIGURATION.

Available options: CONNECTED, PENDING_CONFIGURATION

Example:

"CONNECTED"

correlationId · string · required

Request-scoped correlation identifier echoing X-Request-ID, for pivoting from response to trace.

Example:

"req-7a3f9c2e"

deliveryMode · enum<string> · required

Notification delivery mode: WEBHOOK, EVENT (streaming), or BOTH.

Available options: WEBHOOK, EVENT, BOTH

Example:

"WEBHOOK"

ispb · string · required

Participant ISPB the settings belong to, the 8-character BACEN institution identifier.

Required string length: 8

Pattern: ^[0-9A-Z]{8}$

Example:

"12345678"

webhooks · object[] | null · required

Configured webhook endpoints that receive STR notifications.

Show child attributes

certDaysRemaining · integer<int64>

Whole days remaining until the active certificate expires; absent when no certificate is configured.

Example:

365

certificateExpiresAt · string<date-time>

UTC RFC 3339 expiry timestamp of the active ICP-Brasil certificate; absent when no certificate is configured.

Example:

"2027-05-04T18:30:00Z"

metadata · object

Client-supplied settings metadata; sensitive keys and values are redacted before being returned.

Show child attributes

readiness · object

Embedded readiness summary: aggregate status plus blocker and warning messages. Present only when a readiness source is wired into the settings handler.

Show child attributes