Security policy
This page covers the security policies that keep your use of the Bizgo API safe — API key management, IP ACL setup, enforced HTTPS, and webhook signature verification.
API key security
- Do not hardcode your API key. Use environment variables or a secret management service.
- If your key is exposed, reissue it in the console immediately.
- Keep your development and production API keys separate.
# 잘못된 예
BIZGO_API_KEY = "your_actual_key_here" # 코드에 직접 삽입 금지
# 올바른 예 (.env 파일 또는 시크릿 매니저)
BIZGO_API_KEY = os.environ.get("BIZGO_API_KEY")
// 잘못된 예
const apiKey = "your_actual_key_here"; // ✗
// 올바른 예
const apiKey = process.env.BIZGO_API_KEY; // ✓
IP ACL
The Bizgo API accepts requests only from registered IPs.
- Whenever your server IP changes, update the ACL in the console.
- Keep your development and production API keys separate, and register a different IP range for each.
- You can register IP ranges in CIDR notation:
203.0.113.0/24
A call from an IP that is not registered in the IP ACL is blocked at the authentication or access control step. Look up the
authCodein the response in the code table.
Enforced HTTPS
Every API request must use HTTPS.
HTTP requests are rejected.
Webhook signature verification
When you receive reports by webhook (WEBHOOK), the signature in the request headers tells you whether the request really came from Bizgo.
Always verify the signature to protect against tampering.
The headers you receive:
X-IB-Timestamp: 1743381600000
X-IB-Signature: {Base64(HmacSHA256(secret, X-IB-Timestamp))}
| Header | Description |
|---|---|
X-IB-Timestamp | When the webhook was sent, as a Unix epoch value in milliseconds (ms), sent as a string. |
X-IB-Signature | The X-IB-Timestamp string signed with HMAC-SHA256 using your webhook secret, then Base64-encoded. The request body is not part of the signature. |
- The webhook secret is used only for webhook verification. Ask your sales representative for it, and use the string you receive as the HMAC key as is, without Base64-decoding it.
- To block replay attacks, reject requests whose
X-IB-Timestampdiffers from the current time by more than 300 seconds. This matches the default tolerance of the Bizgo SDKs. - Compare signatures with a constant-time comparison such as
crypto.timingSafeEqual. A===comparison is exposed to timing attacks. - On your firewall, allow only the Bizgo webhook source IPs.
Response specification
Once verification succeeds, return HTTP 200 within 5 seconds with the msgKey you received, as is.
{ "msgKey": "SMS20260331-000001" }
If no response arrives, or the msgKey in your response differs from the one you received, the delivery is treated as failed and resent up to 3 times. If you return only a string such as OK, every attempt is treated as a failure, and once the retries run out you never receive that report.
Verification example (Node.js)
const crypto = require('crypto');
const express = require('express');
const app = express();
const WEBHOOK_SECRET = process.env.BIZGO_WEBHOOK_SECRET;
const TOLERANCE_MS = 300 * 1000; // 허용 오차 300초
function verifySignature(timestamp, signature) {
const sentAt = Number(timestamp); // ms 단위
if (!Number.isFinite(sentAt) || typeof signature !== 'string') return false;
if (Math.abs(Date.now() - sentAt) > TOLERANCE_MS) return false;
const expected = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(timestamp)
.digest('base64');
const a = Buffer.from(expected);
const b = Buffer.from(signature);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post('/webhook/report', express.json(), (req, res) => {
const timestamp = req.get('X-IB-Timestamp');
const signature = req.get('X-IB-Signature');
if (!verifySignature(timestamp, signature)) return res.status(401).end();
// 무거운 처리는 비동기로 분리해 5초 안에 응답
setImmediate(() => processReport(req.body));
// 수신한 msgKey를 그대로 반환 (필수)
res.status(200).json({ msgKey: req.body.msgKey });
});
The signature does not protect the request body. For important decisions such as payment or verification, confirm the result again with the report lookup API.
Mask sensitive data in error logs
Mask sensitive data such as phone numbers and verification codes in your logs.
function maskPhone(phone) {
return phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2');
}
console.log(`발송 대상: ${maskPhone('01012345678')}`); // 010****5678
Next steps
- Environment setup → Set up your environment