개발자 문서
Posmit Notification API는 SMS·이메일·카카오 알림톡·푸시·Slack·Discord까지 8개 채널의 알림 발송을 하나의 REST API로 처리합니다. 채널마다 다른 공급자 연동, 폴백(장애 시 대체 발송), 재시도, 발송 이력 관리를 Posmit이 대신 처리하므로, 여러분의 서버는 “무엇을 누구에게 보낼지”만 요청하면 됩니다.
이 API는 서버 간(server-to-server) 호출 전용입니다. 모든 요청은 API Key와 HMAC-SHA256 서명으로 인증하며, 시크릿이 필요하므로 브라우저나 모바일 앱에서 직접 호출하면 안 됩니다.
베이스 URL
https://api.posmit.io모든 공개 엔드포인트는 /v1 경로 아래에 있습니다. 이 문서의 경로 표기는 베이스 URL 이후의 path만 적습니다.
공통 규약
| 항목 | 내용 |
|---|---|
| 프로토콜 | HTTPS, JSON 요청/응답 (Content-Type: application/json) |
| 인증 | API Key + HMAC-SHA256 서명 헤더 4종 — 인증 |
| 본문 크기 | 최대 1MB |
| 성공 응답 | 모든 2xx 응답은 data + meta.timestamp 봉투(envelope)로 감쌉니다 |
| 에러 응답 | RFC 7807 application/problem+json — 에러 코드 |
| 요청 한도 | API Key당 600회/60초, 워크스페이스당 2,000회/60초 (기본값) — 요청 한도 |
성공 응답 봉투의 형태는 다음과 같습니다.
{
"data": { /* 엔드포인트별 페이로드 */ },
"meta": { "timestamp": "2026-07-10T09:00:00.000Z" }
}요청 본문에 스키마에 정의되지 않은 필드가 있으면 조용히 무시되지 않고 400 에러로 거부됩니다. 필드 이름 오타에 주의하세요.
빠른 시작
첫 SMS 한 건을 발송하기까지의 전체 흐름입니다.
API 키 발급
Posmit 대시보드의 거버넌스 → API 키에서 키를 발급합니다. 발급 직후 응답에서 세 가지 값을 받습니다.
| 값 | 예시 | 용도 |
|---|---|---|
keyId | pk_xxxxxxxxxxxxxxxxxxxx | 키 식별자 |
keySecret | YOUR_KEY_SECRET | X-API-Key 헤더에 keyId와 함께 사용 |
hmacSecret | YOUR_HMAC_SECRET | 요청 서명(HMAC-SHA256) 생성용 |
keySecret과 hmacSecret은 발급 시 단 한 번만 노출됩니다. 분실하면 키를 재발급해야 합니다.
요청 서명 생성
모든 요청에는 X-API-Key, X-Timestamp, X-Nonce, X-Signature 네 개의 헤더가 필요합니다.
서명은 아래 다섯 줄을 개행(\n)으로 이은 canonical string에 hmacSecret으로 HMAC-SHA256을 적용한 값입니다.
METHOD ← 대문자 HTTP 메서드 (예: POST)
PATH ← 쿼리스트링 포함 경로 (예: /v1/notifications)
TIMESTAMP ← X-Timestamp 값 (epoch 초)
NONCE ← X-Nonce 값 (요청마다 새로운 임의 문자열)
BODY_SHA256 ← 요청 본문 원본 바이트의 SHA-256 hex서명 생성 코드는 인증 문서의 예시를 그대로 사용하면 됩니다.
첫 발송
생성한 헤더로 POST /v1/notifications를 호출합니다.
BODY='{"channel":"sms","recipient":{"address":"01012345678"},"content":{"text":"[Posmit] 인증번호는 123456입니다."}}'
curl -X POST https://api.posmit.io/v1/notifications \
-H "Content-Type: application/json" \
-H "X-API-Key: pk_xxxxxxxxxxxxxxxxxxxx.YOUR_KEY_SECRET" \
-H "X-Timestamp: 1752130800" \
-H "X-Nonce: 4f9d2c1b8e7a6f5d4c3b2a10" \
-H "X-Signature: GENERATED_SIGNATURE" \
-d "$BODY"성공하면 HTTP 201과 함께 접수 결과가 반환됩니다. 발송은 비동기로 처리됩니다.
{
"data": {
"status": "queued",
"requestId": "9b2f1c3e-8a4d-4c6e-b7f0-1234567890ab",
"queueJobId": "1234",
"deduplicated": false,
"scheduledAt": null
},
"meta": { "timestamp": "2026-07-10T09:00:00.000Z" }
}결과 확인
응답의 requestId로 발송 상태와 공급자별 시도 이력을 조회합니다. (notifications:read 스코프 필요)
curl https://api.posmit.io/v1/notifications/9b2f1c3e-8a4d-4c6e-b7f0-1234567890ab \
-H "X-API-Key: pk_xxxxxxxxxxxxxxxxxxxx.YOUR_KEY_SECRET" \
-H "X-Timestamp: 1752130860" \
-H "X-Nonce: a1b2c3d4e5f60718293a4b5c" \
-H "X-Signature: GENERATED_SIGNATURE"상태가 queued → processing → sent로 바뀌면 발송이 완료된 것입니다.
폴링 대신 웹훅으로 상태 변화를 실시간으로 받을 수도 있습니다.