Webhook
返信が届いたとき、相手が関心を示したとき、メールがバウンスしたとき、リストやエクスポートの準備ができたときに、署名付きの呼び出しをあなたのサーバーに送ります。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で、返信に関心ありまたは商談の依頼のラベルを付けました。ラベルが変わったときにだけ発生するため、1件の返信では、届いたときに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キーで実行した1件のメールチェックが完了しました | 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、ファイル、リスト、または移動によって、キャンペーンに人物が追加されました。キャンペーンが取り込んだまとまりごとに1回送られるため、大きなインポートは複数回に分かれて届きます。送信前に再び削除された人物は含まれません | 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通分を1回で送ります | 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 |
キャンペーンのイベントは、ワークスペースのオーナーと有効なチームメンバー全員のWebhookに送られるため、各自が自分のツールに向けられます。エクスポート、リスト、チェックのイベントは、それを開始した人のWebhookに送られます。新しい一致は、リストのオーナーのWebhookに送られます。
返信イベントの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は、それを受け取る最初のWebhookが作成されてから約1分後に始まり、それ以前の分は送られません。サーバーの処理が大きく遅れた場合、新しいemail.sentの呼び出しは追いつくまで待機し、破棄されることはありません。
代わりにAPIを定期的に読み取る場合は、毎回の読み取りを前回の終了時刻の数分前から始め、取得済みのIDはスキップしてください。行は記録されている時刻の少しあとに保存されることがあるため、前回の終了時刻ちょうどから始めると取りこぼす可能性があります。Webhookならこうした対応は不要です。
Webhookを作成する
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が含まれます。表示されるのは一度だけなので、すぐに保存してください。各アカウントで有効にできるWebhookは最大10件、合計で最大50件です。登録済みのアドレスを追加すると、そのWebhookが変更され(新しいイベントで有効化)、existing: trueを含む200が返り、新しいシークレットは発行されません。
Webhookの作成には、あなた自身のプラン、またはあなたがチームメンバーとして所属するワークスペースのプランがPro以上である必要があります。それ以外の場合は402 plan_requiredが返ります。上限は人ごとに数えられます。不明なイベントには400 invalid_webhook_eventsが返り、11件目を有効にしようとした場合や51件目を作成しようとした場合は400 webhook_limit_reachedが返ります。
| 呼び出し | 内容 |
|---|---|
GET /api/v1/webhooks | あなたのWebhookと、選択できるすべてのイベント |
PATCH /api/v1/webhooks/{id} | URLやイベントを変更します。"active": falseで無効にできます |
DELETE /api/v1/webhooks/{id} | 削除します |
POST /api/v1/webhooks/{id}/test | イベントのサンプルdataと"test": trueを含む署名付きのテスト呼び出しを1回送ります |
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の4つのキーがあります。数秒以内に任意の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は、Webhookのイベントのいずれかについて、上と同じサンプルdataに"test": trueを加えた署名付きの呼び出しを1回送ります。これにより、コード側でテストと実際のイベントを区別できます。イベントを指定するには{"event": "lead.created"}を送ります。指定しない場合は、Webhookの最初のイベントが使われます。Webhookが受け取らないイベントを指定すると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}}署名を確認する
署名は、シークレットを使って生の本文から計算した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を保存し、一度見たものはスキップしてください。そうすれば、再送された呼び出しは無害になります。
サーバーがダウンしているとき
失敗した呼び出しは、1分後、5分後、30分後、2時間後、6時間後に再試行されるため、最大6回送られます。X-Argorant-Deliveryは1つのイベントのすべての試行で同じなので、処理済みのイベントをスキップするのに使ってください。50回続けて失敗するとWebhookは無効になります。PATCHと"active": trueで再び有効にしてください。404は失敗回数に数えられません。呼び出しは上記のとおり再試行され、あなたのアドレスが7日間404を返し続け、その間に1件も届かなかった場合にのみWebhookが無効になります。410 Goneはアドレスが完全になくなったことを意味するため、Webhookはすぐに削除されます。呼び出しを再び受け取りたい場合は、もう一度追加してください。