웹훅
답장이 오거나, 누군가 관심을 보이거나, 이메일이 반송되거나, 리스트나 내보내기가 준비되면 서명된 호출을 내 서버로 받습니다. Pro 플랜부터 포함됩니다.
이벤트
| 이벤트 | 발생 시점 | data에 담기는 내용 |
|---|---|---|
reply.received | 인물이 내 캠페인 중 하나에 답장했습니다. 워크스페이스에서 부재중 라벨을 숨기지 않았다면 자동 부재 알림은 제외됩니다. 답장을 부재중에서 다른 라벨로 옮길 때도 발생합니다 | classification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at |
reply.positive | 앱에서 또는 POST /api/v1/inbox/{id}/classify로 답장에 관심 있음 또는 미팅 요청 라벨을 달았습니다. 라벨이 바뀔 때만 발생하므로, 답장 하나는 도착할 때 reply.received를, 라벨을 달 때 reply.positive를 보냅니다 | classification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at |
email.bounced | 캠페인 이메일이 반송되었습니다. 그 인물이 이전에 답장한 경우에는 보내지 않습니다 | lead_email, campaign_id, subject |
email.unsubscribed | 누군가 수신 거부 링크를 썼거나, 내가 그 사람의 답장에 수신 거부 라벨을 달았습니다 | classification, lead_email, campaign_id, subject, snippet, 그리고 수신 거부 링크인 경우 source, 라벨에서 온 경우 reply_id, lead_id, received_at |
campaign.paused | Argorant가 실행 중인 캠페인을 일시정지했습니다. 플랜의 캠페인 이메일을 다 썼거나(또는 체험이나 플랜이 끝났거나), 반송이나 오프라인 메일함 때문에 캠페인이 스스로 일시정지한 경우입니다. 내가 직접 일시정지한 경우에는 아무것도 보내지 않습니다 | campaign_id, campaign_name, reason, message, 그리고 campaign_emails(플랜) 또는 metrics와 url(스스로 일시정지) |
campaign.resumed | 캠페인 이메일을 다시 쓸 수 있게 되어(새 달 또는 더 큰 플랜) 플랜 때문에 일시정지된 캠페인이 다시 발송합니다. 내가 직접 시작한 경우에는 아무것도 보내지 않습니다 | campaign_id, campaign_name, reason, message, campaign_emails |
export.ready | 내보내기가 끝났습니다. 실패한 경우에는 보내지 않습니다 | job_id, status, total_rows, verified_rows, status_url, download_url, status_api_path, download_api_path |
list.ready | 리스트 채우기가 끝났습니다. 인물을 더 추가한 뒤에도 발생합니다. 채우기가 실패한 경우에는 보내지 않습니다 | list_id, list_name, job_id, status, total_items, note, status_url, status_api_path |
verification.completed | API 키로 요청한 단일 이메일 검증이 끝났습니다 | email, status, deliverable, is_role_based, is_free, is_disposable |
segment.new_matches | 저장된 검색 리스트에 마지막 집계 때보다 조건에 맞는 인물이 늘었습니다. 리스트는 약 30분마다 확인합니다 | list_id, list_name, previous_total, current_total, new_matches |
lead.created | 앱, API, 파일, 리스트, 이동을 통해 캠페인에 인물이 추가되었습니다. 캠페인이 받아들인 묶음마다 전송이 한 번이므로, 대량 가져오기는 여러 번에 나뉘어 도착합니다. 전송 전에 다시 삭제된 인물은 제외됩니다 | campaign_id, campaign_name, count, leads, 그리고 각 항목의 lead_id, email, first_name, last_name, company, title, status, custom_fields, added_at |
campaign.status_changed | 나 또는 Argorant가 캠페인 상태를 바꿨습니다. 시작, 일시정지, 중지, 보관, 또는 캠페인 이메일, 반송, 오프라인 메일함 때문인 일시정지입니다. campaign.paused와 campaign.resumed와 함께 발생하기도 합니다 | campaign_id, campaign_name, from, to, changed_at |
email.sent | 캠페인 이메일이 발송되었습니다. 발송 후 약 1분 안에 도착하며, 캠페인마다 최대 100통의 이메일을 담아 한 번 전송합니다 | campaign_id, campaign_name, count, emails, 그리고 각 항목의 email_id, lead_id, lead_email, subject, step, mailbox, sent_at |
reply.label_changed | 누군가 앱의 받은편지함에서 또는 POST /api/v1/inbox/{id}/classify로 답장의 라벨을 달거나 바꿨습니다. 같은 라벨을 다시 달면 아무것도 보내지 않습니다 | reply_id, lead_id, lead_email, campaign_id, subject, from, to, changed_at |
캠페인 이벤트는 워크스페이스 소유주와 모든 활성 팀 멤버의 웹훅으로 가므로, 각자 자기 도구로 연결할 수 있습니다. 내보내기, 리스트, 검증 이벤트는 그 작업을 시작한 사람의 웹훅으로 갑니다. 새 일치 항목은 리스트 소유자의 웹훅으로 갑니다.
답장 이벤트에서 classification은 방금 도착한 답장이면 null이고, 누군가 라벨을 달면 positive나 meeting_request 같은 라벨 키가 됩니다. subject는 최대 300자, snippet은 최대 500자의 일반 텍스트를 담습니다. reply_id는 답장, lead_id는 캠페인 속 인물, received_at은 답장이 도착한 시각입니다. campaign.paused의 reason은 플랜 때문에 캠페인이 일시정지되면 campaign_email_allowance이고, 스스로 일시정지하면 auto_pause_bounce_rate, auto_pause_inboxes_offline, auto_pause 중 하나입니다. campaign_emails.reason은 이메일이 바닥난 이유(allowance_used, trial_ended, plan_ended, confirm_email)를 알려 주며, campaign.resumed에서는 비어 있습니다.
campaign.status_changed의 from과 to는 draft, active, paused, completed, archived 중 하나입니다. reply.label_changed에서는 라벨 키이며, 답장에 라벨이 없었으면 from은 null입니다. lead.created, campaign.status_changed, email.sent는 이를 받으려는 첫 웹훅이 만들어지고 약 1분 뒤부터 시작되며, 그 이전의 이벤트는 보내지 않습니다. 내 서버가 크게 뒤처지면 새 email.sent 호출은 서버가 따라잡을 때까지 기다리며, 버려지는 호출은 없습니다.
웹훅 대신 정해진 주기로 API를 읽는다면, 매번 지난번 읽기가 끝난 시점보다 몇 분 앞에서 시작하고 이미 가진 ID는 건너뛰세요. 행은 거기에 기록된 시각보다 조금 늦게 저장될 수 있으므로, 지난번이 끝난 시점에서 정확히 시작하는 구간은 그 행을 놓칠 수 있습니다. 웹훅에서는 이런 처리가 필요 없습니다.
웹훅 만들기
curl -X POST "https://app.argorant.com/api/v1/webhooks" \
-H "Authorization: Bearer $ARGORANT_API_KEY" -H "Idempotency-Key: hook-crm-1" \
-H "Content-Type: application/json" \
-d '{"url":"https://hooks.yourcompany.example/argorant","events":["reply.positive","email.bounced","export.ready"]}'주소는 공개 https:// 주소여야 합니다. 응답에는 서명용 secret이 들어 있습니다. 한 번만 표시되므로 지금 저장하세요. 계정마다 켜 둔 웹훅은 최대 10개, 전체는 50개까지 둘 수 있습니다. 이미 있는 주소를 추가하면 그 웹훅이 바뀌고(새 이벤트, 켜짐), existing: true와 함께 새 secret 없이 200으로 응답합니다.
웹훅을 만들려면 내 플랜이나 내가 팀 멤버로 속한 워크스페이스의 플랜이 Pro 이상이어야 하며, 그렇지 않으면 402 plan_required를 받습니다. 한도는 사람마다 따로 적용됩니다. 알 수 없는 이벤트는 400 invalid_webhook_events로 응답하고, 11번째로 켜는 웹훅이나 전체 51번째 웹훅은 400 webhook_limit_reached로 응답합니다.
| 호출 | 하는 일 |
|---|---|
GET /api/v1/webhooks | 내 웹훅과 고를 수 있는 모든 이벤트 |
PATCH /api/v1/webhooks/{id} | URL이나 이벤트를 바꾸거나, "active": false로 끄기 |
DELETE /api/v1/webhooks/{id} | 삭제 |
POST /api/v1/webhooks/{id}/test | 이벤트의 예시 data와 "test": true를 담은 서명된 테스트 호출 한 번 보내기 |
GET /api/v1/webhooks/{id}/deliveries | 최근 호출과 그 결과, 다음 재시도 |
내 서버가 받는 내용
POST /hooks/argorant
Content-Type: application/json
User-Agent: Argorant-Webhooks/1.0
X-Argorant-Event: reply.positive
X-Argorant-Delivery: 8842
X-Argorant-Signature: sha256=5d41402abc4b2a76b9719d911017c592...
{"event": "reply.positive", "delivery_id": "8842", "created_at": "2026-11-07T09:15:03+00:00",
"data": {"classification": "positive", "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Re: Quick question, Maya", "snippet": "Happy to talk. Does Thursday 10:00 work?", "reply_id": "c4e1a9b2-6d3f-4a7e-9b1c-2f8d0e5a7c63", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "received_at": "2026-11-07T09:14:01.482113+00:00"}}모든 호출에는 같은 네 개의 키 event, delivery_id(텍스트로 보내는 숫자이며 X-Argorant-Delivery와 같음), created_at, data가 있습니다. 몇 초 안에 2xx 상태로 응답하세요. 시간이 걸리는 작업은 응답한 뒤에 하세요. 리디렉션은 따라가지 않으므로 최종 주소를 쓰세요.
페이로드 예시
이벤트마다 내 서버가 받는 그대로의 전체 본문 하나씩입니다. export.ready와 list.ready에는 status_api_path(내보내기에는 download_api_path도)가 함께 들어 있는데, 이는 기존 연동을 위해 남겨 둔 이전 경로이며 아래에서는 생략했습니다. status_url과 download_url을 쓰세요.
reply.received
{"event": "reply.received", "delivery_id": "8841", "created_at": "2026-11-07T09:14:03+00:00",
"data": {"classification": null, "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Re: Quick question, Maya", "snippet": "Happy to talk. Does Thursday 10:00 work?", "reply_id": "c4e1a9b2-6d3f-4a7e-9b1c-2f8d0e5a7c63", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "received_at": "2026-11-07T09:14:01.482113+00:00"}}reply.positive
{"event": "reply.positive", "delivery_id": "8842", "created_at": "2026-11-07T09:15:03+00:00",
"data": {"classification": "positive", "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Re: Quick question, Maya", "snippet": "Happy to talk. Does Thursday 10:00 work?", "reply_id": "c4e1a9b2-6d3f-4a7e-9b1c-2f8d0e5a7c63", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "received_at": "2026-11-07T09:14:01.482113+00:00"}}email.bounced
{"event": "email.bounced", "delivery_id": "8843", "created_at": "2026-11-07T09:16:03+00:00",
"data": {"lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Quick question, Maya"}}email.unsubscribed
{"event": "email.unsubscribed", "delivery_id": "8844", "created_at": "2026-11-07T09:17:03+00:00",
"data": {"classification": "unsubscribe", "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "", "snippet": "", "source": "unsubscribe_link"}}campaign.paused
{"event": "campaign.paused", "delivery_id": "8845", "created_at": "2026-11-07T09:18:03+00:00",
"data": {"campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "reason": "campaign_email_allowance", "message": "Monthly email limit reached. All 300,000 campaign emails for this month are used. Sending resumes on December 1, 2026, or right after an upgrade.", "campaign_emails": {"tier": "pro", "allowance": 300000, "used": 300000, "remaining": 0, "period": "month", "resets_on": "2026-12-01", "reason": "allowance_used", "trial_ends_at": null, "trial_days_left": null}}}campaign.resumed
{"event": "campaign.resumed", "delivery_id": "8846", "created_at": "2026-11-07T09:19:03+00:00",
"data": {"campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "reason": "campaign_email_allowance", "message": "Sending resumed.", "campaign_emails": {"tier": "pro", "allowance": 300000, "used": 0, "remaining": 300000, "period": "month", "resets_on": "2027-01-01", "reason": "", "trial_ends_at": null, "trial_days_left": null}}}export.ready
{"event": "export.ready", "delivery_id": "8847", "created_at": "2026-11-07T09:20:03+00:00",
"data": {"job_id": 84213, "status": "done", "total_rows": 500, "verified_rows": 463, "status_url": "/api/v1/exports/84213", "download_url": "/api/v1/exports/84213/download"}}list.ready
{"event": "list.ready", "delivery_id": "8848", "created_at": "2026-11-07T09:21:03+00:00",
"data": {"list_id": "312", "list_name": "DACH CFOs", "job_id": 5120, "status": "done", "total_items": 1188, "note": "1,240 matched: 1,188 added, 52 already in the list.", "status_url": "/api/v1/lists/312"}}verification.completed
{"event": "verification.completed", "delivery_id": "8849", "created_at": "2026-11-07T09:22:03+00:00",
"data": {"email": "maya.chen@linfieldsystems.example", "status": "valid", "deliverable": true, "is_role_based": false, "is_free": false, "is_disposable": false}}segment.new_matches
{"event": "segment.new_matches", "delivery_id": "8850", "created_at": "2026-11-07T09:23:03+00:00",
"data": {"list_id": "312", "list_name": "DACH CFOs", "previous_total": 1188, "current_total": 1214, "new_matches": 26}}lead.created
{"event": "lead.created", "delivery_id": "8851", "created_at": "2026-11-07T09:24:03+00:00",
"data": {"campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "count": 2, "leads": [{"lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "email": "maya.chen@linfieldsystems.example", "first_name": "Maya", "last_name": "Chen", "company": "Linfield Systems", "title": "CFO", "status": "pending", "custom_fields": {"tags": ["q4"]}, "added_at": "2026-11-07T08:02:11.204519+00:00"}, {"lead_id": "5e2a7c91-3b4d-4f6e-8a1c-9d0b2e4f6a83", "email": "alex.rivera@linfieldsystems.example", "first_name": "Alex", "last_name": "Rivera", "company": "Linfield Systems", "title": "Head of Finance", "status": "pending", "custom_fields": {"tags": ["q4"]}, "added_at": "2026-11-07T08:02:11.204519+00:00"}]}}campaign.status_changed
{"event": "campaign.status_changed", "delivery_id": "8852", "created_at": "2026-11-07T09:25:03+00:00",
"data": {"campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "from": "draft", "to": "active", "changed_at": "2026-11-07T08:05:37.918204+00:00"}}email.sent
{"event": "email.sent", "delivery_id": "8853", "created_at": "2026-11-07T09:26:03+00:00",
"data": {"campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "count": 1, "emails": [{"email_id": "9a7b5c3d-1e2f-4a6b-8c0d-2e4f6a8b0c1d", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "lead_email": "maya.chen@linfieldsystems.example", "subject": "Quick question, Maya", "step": 1, "mailbox": "outreach@yourcompany-mail.example", "sent_at": "2026-11-07T08:31:12.550731+00:00"}]}}reply.label_changed
{"event": "reply.label_changed", "delivery_id": "8854", "created_at": "2026-11-07T09:27:03+00:00",
"data": {"reply_id": "c4e1a9b2-6d3f-4a7e-9b1c-2f8d0e5a7c63", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Re: Quick question, Maya", "from": null, "to": "meeting_request", "changed_at": "2026-11-07T09:20:41Z"}}테스트 호출
POST /api/v1/webhooks/{id}/test는 웹훅의 이벤트 중 하나에 대해 위와 같은 예시 data에 "test": true를 더한 서명된 호출 한 번을 보내므로, 코드에서 테스트와 실제 이벤트를 구분할 수 있습니다. 이벤트를 고르려면 {"event": "lead.created"}를 보내세요. 없으면 웹훅의 첫 번째 이벤트를 씁니다. 웹훅이 받지 않는 이벤트는 400 event_not_subscribed로 응답합니다.
{"event": "reply.positive", "delivery_id": "9012", "created_at": "2026-11-07T09:30:03+00:00",
"data": {"classification": "positive", "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Re: Quick question, Maya", "snippet": "Happy to talk. Does Thursday 10:00 work?", "reply_id": "c4e1a9b2-6d3f-4a7e-9b1c-2f8d0e5a7c63", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "received_at": "2026-11-07T09:14:01.482113+00:00", "test": true}}서명 확인하기
서명은 secret으로 계산한 원본 본문의 HMAC-SHA256입니다. 호출을 믿기 전에 서명을 비교하세요. JSON으로 파싱하기 전에, 도착한 그대로의 본문 바이트를 쓰세요.
import hmac, hashlib
def is_from_argorant(secret: str, raw_body: bytes, signature_header: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature_header)const crypto = require("crypto");
function isFromArgorant(secret, rawBody, signatureHeader) {
const expected = Buffer.from("sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex"));
const given = Buffer.from(signatureHeader || "");
return given.length === expected.length && crypto.timingSafeEqual(expected, given);
}서명된 본문에는 delivery_id와 created_at이 들어 있어서, 서명을 깨뜨리지 않고는 둘 다 바꿀 수 없습니다. 처리한 전송 ID를 보관해 두고, 이미 본 ID는 건너뛰세요. 그러면 재전송된 호출이 해를 끼치지 않습니다.
내 서버가 다운되었을 때
실패한 호출은 1분, 5분, 30분, 2시간, 6시간 후에 다시 시도되므로 최대 6번 전송됩니다. 한 이벤트의 모든 시도에서 X-Argorant-Delivery는 같으므로, 이를 사용해 이미 처리한 이벤트를 건너뛰세요. 50번 연속으로 호출이 실패하면 웹훅이 꺼집니다. PATCH와 "active": true로 다시 켜세요. 404는 실패로 세지 않습니다. 호출은 위와 같이 다시 시도되며, 7일 동안 내 주소가 404로 응답하고 성공한 호출이 하나도 없을 때만 웹훅이 꺼집니다. 410 Gone은 주소가 영구적으로 없어졌다는 뜻이므로 웹훅이 즉시 삭제됩니다. 호출을 다시 받고 싶으면 웹훅을 다시 추가하세요.