Rotate the signing secret

POST

/gateway/webhooks/config/rotate

• Shared development environment (test money only)

Required scope: webhooks:write.

Returns the new secret once. The previous secret stays valid for 24 hours.

Rotates first active endpoint. Store the new secret; retain previous version during the advertised grace window.

Authorizations

• apiKeyAuth

Responses

200

Success

object

message

required

string

previous_secret_grace_hours

required

integer

secret

required

string

secret_version

required

integer

webhook_id

required

string format: uuid

400

Validation error

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object

error

required

Machine code (SCREAMING_SNAKE)

string

Example

VALIDATION_ERROR

message

required

Human-readable detail

string

Example

amount_ghs must be greater than zero

request_id

required

Mirrors the x-request-id response header

string format: uuid

retriable

required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean

timestamp

required

string format: date-time

401

Invalid key

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object

error

required

Machine code (SCREAMING_SNAKE)

string

Example

VALIDATION_ERROR

message

required

Human-readable detail

string

Example

amount_ghs must be greater than zero

request_id

required

Mirrors the x-request-id response header

string format: uuid

retriable

required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean

timestamp

required

string format: date-time

403

Scope, merchant or environment denied

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object

error

required

Machine code (SCREAMING_SNAKE)

string

Example

VALIDATION_ERROR

message

required

Human-readable detail

string

Example

amount_ghs must be greater than zero

request_id

required

Mirrors the x-request-id response header

string format: uuid

retriable

required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean

timestamp

required

string format: date-time

404

Not found

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object

error

required

Machine code (SCREAMING_SNAKE)

string

Example

VALIDATION_ERROR

message

required

Human-readable detail

string

Example

amount_ghs must be greater than zero

request_id

required

Mirrors the x-request-id response header

string format: uuid

retriable

required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean

timestamp

required

string format: date-time

409

Intent conflict

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object

error

required

Machine code (SCREAMING_SNAKE)

string

Example

VALIDATION_ERROR

message

required

Human-readable detail

string

Example

amount_ghs must be greater than zero

request_id

required

Mirrors the x-request-id response header

string format: uuid

retriable

required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean

timestamp

required

string format: date-time

429

Rate limited

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object

error

required

Machine code (SCREAMING_SNAKE)

string

Example

VALIDATION_ERROR

message

required

Human-readable detail

string

Example

amount_ghs must be greater than zero

request_id

required

Mirrors the x-request-id response header

string format: uuid

retriable

required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean

timestamp

required

string format: date-time

500

Internal error

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object

error

required

Machine code (SCREAMING_SNAKE)

string

Example

VALIDATION_ERROR

message

required

Human-readable detail

string

Example

amount_ghs must be greater than zero

request_id

required

Mirrors the x-request-id response header

string format: uuid

retriable

required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean

timestamp

required

string format: date-time

503

Service unavailable

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object

error

required

Machine code (SCREAMING_SNAKE)

string

Example

VALIDATION_ERROR

message

required

Human-readable detail

string

Example

amount_ghs must be greater than zero

request_id

required

Mirrors the x-request-id response header

string format: uuid

retriable

required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean

timestamp

required

string format: date-time