Strails Management API: Webhooks, Keys & IP Allowlist

Use the Management API to configure the operational settings for your Strails integration - register and toggle webhook endpoints, manage IP allowlist rules that guard your API access, rotate your API key, and set per-user onramp asset preferences. You can also inspect the auto-signing threshold assigned to your fintech for cNGN buying.

Endpoints overview

Section	Endpoint	Method	Description
Regenerate API Key	`/regenerateapikey`	GET	Generate a new API key, immediately invalidating the old one
Store Public Key	`/storepublickey`	POST	Store your X25519 public key for response and webhook encryption
Get Platform Public Key	`/getplatformpublickey`	GET	Retrieve the platform X25519 public key used to encrypt requests
Get AES Key	`/getaeskey`	GET	Retrieve your raw, unmasked AES key for legacy operations
Set Webhook	`/setwebhook`	POST	Configure your webhook URL, optional secret, and event subscriptions
Toggle Webhook Status	`/togglewebhookstatus`	POST	Enable or disable webhook delivery without changing the URL
Get Webhook	`/getwebhook`	GET	Retrieve your current webhook configuration
Manage IP Allowlist	`/manageipallowlist`	POST	Add, remove, list, or check IP addresses on your allowlist
Update Onramp Asset	`/updateonrampasset`	POST	Update a user’s onramp asset preferences
Auto Signing Config	`/autosigning/config`	GET	Retrieve your auto-approval threshold for cNGN buying
Create Sandbox API Key	`/createsandboxapikey`	POST	Create a sandbox-only API key for mock environment testing

GET /regenerateapikey

Generate a fresh API key for your fintech account.

Calling this endpoint immediately invalidates your existing API key. Any requests still using the old key will be rejected. Store your new key securely before making further API calls - it will not be shown again.

Request

curl --request GET \
  --url "{{BASE_URL}}/regenerateapikey" \
  --header "x-api-key: YOUR_CURRENT_API_KEY"

Response

string

Your new API key. Copy and store this value immediately - it is only returned once.

string

ISO 8601 timestamp recording when the key was rotated.

{
  "status": "Success",
  "response_code": "00",
  "message": "API key regenerated successfully",
  "data": {
    "apiKey": "key-xxxxxxxxxxxxxxxxx",
    "rotatedAt": "2025-08-26T10:20:00.000Z"
  }
}

POST /setwebhook

Register or update the webhook endpoint that Strails uses to deliver event notifications to your server. You can also attach a signing secret so you can verify each delivery. For details on verifying the HMAC signature included with every webhook delivery, see the HMAC Signatures page.

Body parameters

string

required

The publicly reachable HTTPS URL on your server that will receive POST requests for webhook events.

string

A secret string used by Strails to sign outgoing webhook payloads. Include this to enable signature verification on your end.

boolean

required

Set to true to activate delivery to this URL immediately, or false to register it in a disabled state.

array

List of event types to subscribe to. Pass ["all"] to receive every event type. Refer to the Webhook Events page for all available event names.

Request

curl --request POST \
  --url "{{BASE_URL}}/setwebhook" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "webhookUrl": "https://your-domain.com/webhook",
    "secret": "your_webhook_secret_key",
    "enabled": true,
    "events": ["all"]
  }'

Response

string

The URL that was registered.

boolean

Current delivery status of the webhook.

boolean

true if a signing secret is configured for this webhook.

boolean

true if Strails was able to reach and validate the provided URL.

string

ISO 8601 timestamp of when the configuration was saved.

{
  "status": "Success",
  "response_code": "00",
  "message": "Webhook configured successfully",
  "data": {
    "webhookUrl": "https://your-domain.com/webhook",
    "enabled": true,
    "hasSecret": true,
    "urlValidated": true,
    "updatedAt": "2025-08-26T11:00:00.000Z"
  }
}

POST /togglewebhookstatus

Enable or disable webhook delivery without modifying the registered URL or signing secret. Use this to pause notifications during maintenance windows or re-enable them when you are ready.

Body parameters

boolean

required

Set to true to resume webhook delivery or false to pause it.

Request

curl --request POST \
  --url "{{BASE_URL}}/togglewebhookstatus" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "enabled": true
  }'

Response

string

Your registered webhook URL (partially masked for security).

boolean

The new delivery status that was applied.

string

ISO 8601 timestamp of when the status change took effect.

{
  "status": "Success",
  "response_code": "00",
  "message": "Webhook activated successfully",
  "data": {
    "webhookUrl": "htt***com/webhook",
    "enabled": true,
    "updatedAt": "2026-06-23T12:00:00.000Z"
  }
}

GET /getwebhook

Retrieve your current webhook configuration, including the registered URL (partially masked), delivery status, and whether a signing secret is set.

Request

curl --request GET \
  --url "{{BASE_URL}}/getwebhook" \
  --header "x-api-key: YOUR_API_KEY"

Response

string

Your registered webhook URL, partially masked to protect the full path.

boolean

true if webhook delivery is currently active.

boolean

true if a signing secret is attached to this webhook configuration.

array

The list of event types currently subscribed. Returns ["all"] if you subscribed to all events.

string

ISO 8601 timestamp of the last configuration update.

{
  "status": "Success",
  "response_code": "00",
  "message": "Webhook configuration retrieved successfully",
  "data": {
    "webhookUrl": "https://sgh***.ms/webhook",
    "enabled": true,
    "hasSecret": true,
    "events": ["all"],
    "updatedAt": "2026-01-29T05:11:06.862Z"
  }
}

POST /storepublickey

Register your X25519 public key with Strails. Once stored, Strails uses it to encrypt all response payloads and webhook bodies sent to your integration via libsodium crypto_box_seal.

Body parameters

string

required

A 64-character hex X25519 public key, or the AES-encrypted legacy envelope whose decrypted data is the same 64-hex X25519 public key.

Request

curl --request POST \
  --url "{{BASE_URL}}/storepublickey" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "data": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
  }'

Response

string

ISO 8601 timestamp of when the public key was stored.

{
  "status": "Success",
  "response_code": "00",
  "message": "Public key stored successfully",
  "data": {
    "updatedAt": "2025-08-26T10:30:00.000Z"
  }
}

GET /getplatformpublickey

Retrieve the Strails platform X25519 public key. Use this key to seal request payloads with libsodium crypto_box_seal so only Strails can decrypt them.

Request

curl --request GET \
  --url "{{BASE_URL}}/getplatformpublickey" \
  --header "x-api-key: YOUR_API_KEY"

Response

string

The 64-character hex Strails X25519 public key.

{
  "status": "Success",
  "response_code": "00",
  "message": "Platform public key retrieved successfully",
  "data": {
    "publicKey": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
  }
}

GET /getaeskey

Retrieve your raw, unmasked AES key. This key is used for legacy AES-GCM payload encryption and as a fallback for webhook signature verification when no dedicated webhook secret is configured.

Treat your AES key as a sensitive secret. Do not log it, expose it in client-side code, or commit it to version control.

Request

curl --request GET \
  --url "{{BASE_URL}}/getaeskey" \
  --header "x-api-key: YOUR_API_KEY"

Response

string

Your raw AES key.

{
  "status": "Success",
  "response_code": "00",
  "message": "AES key retrieved successfully",
  "data": {
    "aesKey": "your_aes_key_value"
  }
}

POST /manageipallowlist

Manage the set of IP addresses permitted to make API requests on behalf of your fintech account. You can list all allowed IPs, add a new address, remove an existing one by address or index, or check whether your current request IP is on the list.

In production, all servers originating API requests must have their IP addresses on your allowlist. IP changes propagate to all servers within 30 seconds.

Body parameters

string

required

The operation to perform. Accepted values: "list", "add", "remove", "check".

string

The IP address to add, remove, or check. Required when action is "add" or when removing by address. Not required for "list" or "check".

number

Zero-based index of the IP to remove, as returned by the "list" action. Use this as an alternative to specifying ipAddress when removing an entry.

string

Optional label describing the IP address (e.g., "Office network IP"). Used with the "add" action.

List all allowed IPs

curl --request POST \
  --url "{{BASE_URL}}/manageipallowlist" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "action": "list" }'

{
  "status": "Success",
  "response_code": "00",
  "message": "IP allowlist operation completed",
  "data": {
    "action": "list",
    "ipAddresses": [
      { "index": 0, "ip": "203.0.***.***", "description": "Office network" },
      { "index": 1, "ip": "192.168.***.***", "description": "VPN endpoint" }
    ],
    "totalIps": 2
  }
}

Add an IP address

curl --request POST \
  --url "{{BASE_URL}}/manageipallowlist" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "action": "add",
    "ipAddress": "203.0.113.45",
    "description": "Office network IP"
  }'

{
  "status": "Success",
  "response_code": "00",
  "message": "IP allowlist operation completed",
  "data": {
    "action": "add",
    "ipAddress": "203.0.***.***",
    "totalIps": 4,
    "message": "IP address added successfully. Changes will take effect within 30 seconds across all servers.",
    "propagationTime": "30 seconds"
  }
}

Remove an IP address

curl --request POST \
  --url "{{BASE_URL}}/manageipallowlist" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "action": "remove",
    "ipAddress": "10.0.0.5"
  }'

{
  "status": "Success",
  "response_code": "00",
  "message": "IP allowlist operation completed",
  "data": {
    "action": "remove",
    "removed": "203.0.***.***",
    "totalIps": 2,
    "message": "IP address removed successfully. Changes will take effect within 30 seconds across all servers.",
    "propagationTime": "30 seconds"
  }
}

Check your current IP

curl --request POST \
  --url "{{BASE_URL}}/manageipallowlist" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "action": "check" }'

{
  "status": "Success",
  "response_code": "00",
  "message": "IP allowlist operation completed",
  "data": {
    "action": "check",
    "yourIp": "192.168.***.***",
    "isAllowed": true,
    "matchedRule": "192.168.***.***",
    "totalConfiguredIps": 3,
    "note": "Your IP is allowed. Cache refreshed on this server instance.",
    "cacheInfo": {
      "ttlSeconds": 30,
      "propagationTime": "Changes propagate to other servers within 30 seconds",
      "cacheRefreshed": true
    }
  }
}

POST /updateonrampasset

Update the onramp asset preferences for a specific user on your platform. Use this to configure which token a user receives by default when they fund via onramp, whether to auto-swap on arrival, and the acceptable slippage tolerance.

Body parameters

string

required

The unique identifier (hash or UUID) of the user whose preferences you are updating.

string

Asset symbol to set as the user’s preferred onramp target (e.g., "USDC", "cNGN").

object

Extended asset preference configuration for the user.

Show preferences fields

string

Asset symbol set as the default for swaps or funding (e.g., "USDC").

boolean

When true, deposited assets are automatically swapped into defaultAsset upon receipt.

string

Maximum allowable slippage for auto-swap operations, expressed as a percentage string (e.g., "0.5" for 0.5%).

Request

curl --request POST \
  --url "{{BASE_URL}}/updateonrampasset" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "userId": "user_hash",
    "preferences": {
      "defaultAsset": "USDC",
      "autoSwap": true,
      "slippageTolerance": "0.5"
    }
  }'

Response

string

Unique identifier for this update operation.

string

ISO 8601 timestamp of when the preferences were saved.

boolean

The autoSwap value that was applied for this user.

{
  "status": "00",
  "message": "Asset settings updated successfully",
  "data": {
    "requestId": "op_uuid",
    "updatedAt": "2025-08-26T09:58:30.000Z",
    "autoSwap": true
  }
}

GET /autosigning/config

Retrieve the auto-approval threshold configuration assigned to your fintech account for cNGN buying. When a transaction amount is at or below this threshold, it is approved automatically without requiring manual signing.

Request

curl --request GET \
  --url "{{BASE_URL}}/autosigning/config" \
  --header "x-api-key: YOUR_API_KEY"

Response

boolean

true if auto-signing is active for your fintech account.

string

The maximum cNGN amount that qualifies for automatic approval. Transactions above this value require manual signing.

string

The token denomination for the threshold amount. Typically "CNGN".

string

The cumulative daily cap for auto-signed transactions.

boolean

true if auto-signing is scoped to transactions originating from your fintech account only.

{
  "status": "Success",
  "response_code": "00",
  "message": "Configuration retrieved successfully",
  "data": {
    "enabled": true,
    "thresholdAmount": "***",
    "currency": "CNGN",
    "maxDailyAmount": "100000000",
    "restrictToFintech": true
  }
}

POST /createsandboxapikey

Create a sandbox-only API key for testing against the mock sandbox environment. This key is separate from your production API key and can only be used with sandbox endpoints.

Request

curl --request POST \
  --url "{{BASE_URL}}/createsandboxapikey" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json"

Response

string

The newly created sandbox API key. Store this value securely - it is only returned once.

string

The fintech ID associated with the sandbox key.

string

ISO 8601 timestamp of when the sandbox API key was created.

string

Reminder that this key is valid only for the mock sandbox environment.

{
    "status": "Success",
    "response_code": "00",
    "message": "Sandbox API key created successfully",
    "data": {
        "apiKey": "sandbox_4cda698e926f4ee2b0baa",
        "fintechId": "fintech-Id",
        "createdAt": "2026-07-29T16:52:49.420Z",
        "note": "This key is valid only for the mock sandbox environment."
    }
}

​Endpoints overview

​GET /regenerateapikey

​Request

​Response

​POST /setwebhook

​Body parameters

​Request

​Response

​POST /togglewebhookstatus

​Body parameters

​Request

​Response

​GET /getwebhook

​Request

​Response

​POST /storepublickey

​Body parameters

​Request

​Response

​GET /getplatformpublickey

​Request

​Response

​GET /getaeskey

​Request

​Response

​POST /manageipallowlist

​Body parameters

​List all allowed IPs

​Add an IP address

​Remove an IP address

​Check your current IP

​POST /updateonrampasset

​Body parameters

​Request

​Response

​GET /autosigning/config

​Request

​Response

​POST /createsandboxapikey

​Request

​Response

Endpoints overview

GET /regenerateapikey

Request

Response

POST /setwebhook

Body parameters

Request

Response

POST /togglewebhookstatus

Body parameters

Request

Response

GET /getwebhook

Request

Response

POST /storepublickey

Body parameters

Request

Response

GET /getplatformpublickey

Request

Response

GET /getaeskey

Request

Response

POST /manageipallowlist

Body parameters

List all allowed IPs

Add an IP address

Remove an IP address

Check your current IP

POST /updateonrampasset

Body parameters

Request

Response

GET /autosigning/config

Request

Response

POST /createsandboxapikey

Request

Response