ArgorantDocs

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.completedAPIキーで実行した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を作成する

Shell
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最近の呼び出しと、その結果および次回の再試行

サーバーが受け取る内容

HTTP
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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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が返ります。

JSON
{"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として解析する前の、届いたままの本文のバイト列を使います。

Python
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)
Node
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はすぐに削除されます。呼び出しを再び受け取りたい場合は、もう一度追加してください。

このページの内容