# 서명된 웹훅을 지원하는 CRM REST API | AiCrm

> 공개 REST API를 제공하는 CRM: X-Api-Key 헤더로 연락처를 만들고 조회하세요. 연동별 키는 최대 20개, HMAC-SHA256으로 서명된 웹훅도 지원해요. 웹사이트 리드를 중복 없이 등록해요.

- **출처 (source):** https://aistohire.com/ko/aicrm-api-gyeongnyang-crm-109/f/crm-rest-api-seomyeong-webhook
- **플랫폼 (platform):** AIstoHire
- **언어 (language):** ko

## 요약

- 여러 API 키와 서명된 웹훅을 지원하는 공개 REST API
- 웹사이트, 양식, 백엔드에서 HTTP 호출 한 번으로 고객을 등록하고, 모든 변경 사항을 HMAC-SHA256으로 서명해 서버로 받아 보세요.
- API 한 번 호출로 연락처 등록
- 설계부터 중복이 없어요. 이메일이 이미 있으면 카드를 업데이트하고 새 제출 내역을 타임라인에 기록할 뿐, 두 번째 카드를 만들지 않아요.
- 이름을 붙인 키를 최대 20개까지 만들 수 있어요. 연동마다 하나씩 쓰고 따로 폐기할 수 있어요. 키가 유출되면 그 키만 삭제하면 되고, 다른 것은 영향이 없어요.

## 여러 API 키와 서명된 웹훅을 지원하는 공개 REST API

AIsToHire의 CRM 앱인 AiCrm은 내 연락처에 대한 공개 REST API를 제공해요. `X-Api-Key` 헤더에 키를 담으면 웹사이트 양식, 챗봇, Zap, Python 스크립트, 자체 백엔드 어디에서든 연락처를 생성, 목록 조회, 상세 조회, 수정, 삭제하고 연락처에 활동을 추가할 수 있어요. 응답은 `{ success, data }` 형태의 JSON이고, 제한은 키당 분당 100건이에요.

API로 등록해도 중복이 생기지 않아요. 보낸 이메일이 이미 DB에 있으면 AiCrm이 기존 카드를 업데이트하고(빠져 있던 전화번호, 이름, 회사를 채우고 태그를 합쳐요) 타임라인에 새 제출 내역을 기록한 뒤 HTTP 200을 반환해요. 새로운 연락처면 생성하고 201을 반환해요. API로 들어온 연락처에는 자동으로 `api-lead` 태그가 붙고, 보낸 태그가 유지되며, 유입 `subId`와 함께 접속한 국가, IP, 브라우저도 저장돼요.

이름을 붙인 API 키를 앱 내부 키와 별개로 최대 20개까지 만들 수 있어요. 웹사이트, 5월 캠페인 양식, 인턴, 협력업체처럼 연동마다 다른 키를 주고, 해당 연동이 끝나면 다른 것은 건드리지 않고 그 키만 폐기하면 돼요. 키의 전체 값은 만들 때 단 한 번만 표시되고, 이후 목록에서는 가려진 상태로만 보여요.

반대 방향으로는 웹훅이 시스템에 알려 줘요. 대상을 최대 10개까지 설정하고 각각이 구독할 이벤트(`customer.created`, `customer.updated`, `customer.deleted`, `activity.created`)를 고르면, AiCrm이 `X-AiCrm-Event`와 `X-AiCrm-Signature: sha256=…` 헤더를 붙여 내 URL로 POST해요. 서명은 해당 웹훅의 비밀 키로 본문에 대해 계산한 HMAC-SHA256 값이므로 전송이 정상인지 검증할 수 있어요. URL을 저장할 때 SSRF 방어 기능이 localhost, 127.0.0.0/8, 10.x, 192.168.x, 172.16-31.x, ::1, 0.0.0.0, 그리고 `.local`과 `.internal` 도메인을 거부해요.

## 포함된 내용

- **API 한 번 호출로 연락처 등록** — 이메일과 원하는 태그를 담아 `/api/apps/public/crm/customers`로 POST하면, 리드가 분류된 상태로 CRM에 바로 들어와요.
- 설계부터 중복이 없어요. 이메일이 이미 있으면 카드를 업데이트하고 새 제출 내역을 타임라인에 기록할 뿐, 두 번째 카드를 만들지 않아요.
- 이름을 붙인 키를 최대 20개까지 만들 수 있어요. 연동마다 하나씩 쓰고 따로 폐기할 수 있어요. 키가 유출되면 그 키만 삭제하면 되고, 다른 것은 영향이 없어요.
- **HMAC-SHA256으로 서명된 웹훅** — 비밀 키로 `X-AiCrm-Signature` 헤더를 검증하면, 알림이 제3자가 아닌 내 CRM에서 온 것임을 확인할 수 있어요.
- SSRF 방어 기능이 기본 제공돼요. 앱이 localhost나 사설 네트워크 대역으로는 웹훅을 전달하지 않으므로, CRM이 내부 네트워크를 탐색하는 데 악용될 수 없어요.
- 등록만 되는 게 아니라 CRUD를 모두 지원해요. 페이지네이션과 필터(검색, 상태, 태그, 국가)로 목록 조회, 활동 내역을 포함한 연락처 조회, 수정, 삭제, 활동 기록까지 가능해요.
- 유입 경로가 자동으로 기록돼요. API로 등록할 때마다 보내 준 `subId`와 국가, IP, 브라우저가 저장되고 `api-lead` 태그가 붙으므로 나중에 앱에서 쉽게 필터링할 수 있어요.
- 추측 없이 테스트해요. 앱에 복사해서 쓸 수 있는 `curl` 예시가 포함된 엔드포인트 문서가 있고, 각 웹훅에 테스트 전송을 보내는 버튼과 마지막 시도의 상태 및 시각도 확인할 수 있어요.

## 자주 묻는 질문

### 웹사이트에서 CRM에 연락처를 어떻게 만드나요?

`X-Api-Key` 헤더와 최소한 이메일 또는 전화번호가 담긴 JSON을 `/api/apps/public/crm/customers`로 POST해요. 이름, 전화번호, 회사, 국가, 상태, 메모, 태그, 그리고 캠페인이나 유입 양식을 식별하는 `subId`도 함께 보낼 수 있어요. AiCrm은 새로 만들면 201을, 이미 있는 연락처면 200을 반환해요.

### 같은 이메일이 API로 두 번 들어오면 어떻게 되나요?

중복되지 않아요. AiCrm이 이메일(이메일이 없으면 전화번호)로 검색하고, 찾으면 기존 카드를 업데이트해요. 비어 있던 필드는 채우고, 새 태그는 기존 태그와 합치며, 새 제출 내역을 활동 타임라인에 기록해요. 응답에는 이미 있던 연락처라는 표시와 함께 해당 id가 반환돼요.

### API 키는 몇 개까지 만들 수 있고, 하나만 폐기할 수도 있나요?

이름을 붙인 키를 최대 20개까지 만들 수 있고, 삭제할 수 없는 앱 내부 키도 별도로 있어요. 각 키는 독립적으로 삭제되므로 연동마다 다른 키를 주고 나머지에 영향 없이 폐기할 수 있어요. 키 전체 값은 만드는 순간에만 표시되고, 이후 목록에서는 가려진 상태로 보여요. 모든 키는 키당 분당 100건 요청 제한이 적용돼요.

### 웹훅이 정말 내 CRM에서 온 것인지 어떻게 확인하나요?

모든 전송에는 `X-AiCrm-Signature: sha256=<서명>` 헤더가 포함돼요. 웹훅을 만들 때 앱이 보여 주는 비밀 키로 요청 본문 원문 전체에 대해 계산한 HMAC-SHA256 값이에요. 서버에서 받은 본문으로 같은 HMAC을 계산해 비교하세요. 이벤트 이름이 담긴 `X-AiCrm-Event` 헤더도 함께 전달돼요. 값은 `customer.created`, `customer.updated`, `customer.deleted`, `activity.created` 중 하나예요.

### 웹훅 엔드포인트가 다운되면 어떻게 되나요?

전송은 best-effort 방식이에요. AiCrm이 최대 5초 기다리고, 실패하면 1.5초 후에 한 번 재시도해요. 영구적인 재시도 큐는 없으므로 서버가 오래 다운되면 알림을 놓칠 수 있어요. 그럴 때는 `/api/apps/public/crm/customers`에 GET으로 조회해 맞춰 보세요. 앱에서 각 웹훅의 마지막 시도 상태와 시각을 확인할 수 있고, 테스트 전송은 언제든 실행할 수 있어요.

- [AiCrm — 어떤 시스템에서든 고객을 등록하는 API 기반 경량 CRM](https://aistohire.com/ko/aicrm-api-gyeongnyang-crm-109)

## 플랫폼 소개

**AiCrm — 어떤 시스템에서든 고객을 등록하는 API 기반 경량 CRM** — 앱 개발: AIstoHire. 이용 가능 위치:: https://aistohire.com/ko/aicrm-api-gyeongnyang-crm-109/f/crm-rest-api-seomyeong-webhook

### 다른 언어

- `es`: https://aistohire.com/es/aicrm-crm-ligero-con-api-109/f/api-rest-crm-webhooks-firmados
- `en`: https://aistohire.com/aicrm-lightweight-crm-with-api-109/f/api-rest-crm-signed-webhooks
- `fr`: https://aistohire.com/fr/aicrm-crm-leger-avec-api-109/f/api-rest-crm-webhooks-signes
- `it`: https://aistohire.com/it/aicrm-crm-leggero-con-api-109/f/api-rest-crm-webhook-firmati
- `pt`: https://aistohire.com/pt/aicrm-crm-leve-com-api-109/f/api-rest-crm-webhooks-assinados
- `de`: https://aistohire.com/de/aicrm-leichtes-crm-mit-api-109/f/api-rest-crm-signierte-webhooks
- `bg`: https://aistohire.com/bg/aicrm-lesen-crm-s-api-za-upravlenie-na-klienti-i-liydove-109/f/rest-api-crm-podpisani-uebhukove
- `ja`: https://aistohire.com/ja/aicrm-lightweight-crm-with-api-109/f/crm-rest-api-signed-webhooks
- `nl`: https://aistohire.com/nl/aicrm-eenvoudige-crm-met-api-om-klanten-en-leads-te-beheren-109/f/rest-api-crm-ondertekende-webhooks
- `sv`: https://aistohire.com/sv/aicrm-enkelt-crm-med-api-for-att-hantera-kunder-och-leads-109/f/rest-api-crm-signerade-webhooks
- `da`: https://aistohire.com/da/aicrm-enkelt-crm-med-api-til-at-styre-kunder-og-leads-109/f/rest-api-crm-signerede-webhooks
- `ar`: https://aistohire.com/ar/aicrm-nzam-crm-bsit-ma-api-lidara-alamla-walamla-almhtmlin-109/f/crm-rest-api-webhooks
- `no`: https://aistohire.com/no/aicrm-enkelt-crm-med-api-for-a-styre-kunder-og-leads-109/f/rest-api-crm-signerte-webhooks
- `fi`: https://aistohire.com/fi/aicrm-yksinkertainen-crm-rajapinnalla-asiakkaille-ja-liideille-109/f/crm-rest-api-allekirjoitetut-webhookit
- `zh`: https://aistohire.com/zh/ai-crm-rest-api-webhooks-109/f/crm-rest-api-webhook
- `pl`: https://aistohire.com/pl/aicrm-prosty-crm-z-api-do-zarzadzania-klientami-i-leadami-109/f/api-rest-crm-podpisane-webhooki
- `he`: https://aistohire.com/he/aicrm-crm-pshot-am-api-lnihol-lkochot-vlidim-109/f/api-rest-crm-webhooks-chatumim
- `cs`: https://aistohire.com/cs/aicrm-jednoduche-crm-s-api-pro-spravu-klientu-a-leadu-109/f/rest-api-crm-podepsane-webhooky
- `id`: https://aistohire.com/id/aicrm-crm-sederhana-dengan-api-untuk-mengelola-pelanggan-dan-lead-109/f/api-rest-crm-webhook-bertanda-tangan
