Skip to main content

API Keys, Webhooks, and IP Allowlists

What Are API Keys, Webhooks, and IP Allowlists​

An API Key lets a server call the ORBSIS REST API directly. A Webhook pushes events such as transactions to your system in real time. An IP allowlist restricts which network addresses can access your API. Together, they form the technical foundation for enterprise-system integration.

Why These Integration Capabilities Matter​

Compared with manual sign-in, API integration lets an organization’s systems automate repetitive tasks such as searches, card creation, and reconciliation. Webhooks avoid the delay of polling transaction statuses, while IP allowlists provide an additional layer of protection if a secret is exposed.

How to Use API Keys, Webhooks, and IP Allowlists​

Create an API Key​

API Keys are suitable for server-side integrations. Before creating one, define its purpose, owner, and runtime environment; avoid sharing one key across multiple systems.

Important A Secret Key is usually shown only once when it is created. Save it immediately in a secrets-management system. Do not put it in source code, chat tools, tickets, or customer documentation.

Configure a Webhook​

Webhooks push transactions and other events to your system. The receiver must verify the signature using the original request body and the agreed algorithm before processing the event.

  • Verify ORBSIS-Signature with HMAC-SHA256;
  • Use HTTPS for the endpoint and return a success status quickly;
  • Process events idempotently by event ID to prevent duplicate postings caused by retries;
  • Record the receipt time, signature-verification result, and processing result, but never record the full secret.

Restrict API Access by IP​

An IP allowlist can restrict API access to specified IPv4, IPv6, or CIDR ranges. Before adding entries, confirm the fixed egress IPs of the production environment and keep a secure recovery method.

Activation rule When the allowlist is empty, the API can be accessed from any IP. After the first entry is added, only allowlisted IPs or ranges can access it. An incorrect configuration may immediately interrupt existing integrations.