# 署名付きWebhookを備えたCRM向けREST API | AiCrm

> 公開REST APIを備えたCRM。X-Api-Keyヘッダーで連絡先を作成・取得、連携ごとに最大20個のキー、HMAC-SHA256署名付きの送信Webhook。Webサイトからのリード登録も重複なし。

- **ソース (source):** https://aistohire.com/ja/aicrm-lightweight-crm-with-api-109/f/crm-rest-api-signed-webhooks
- **プラットフォーム (platform):** AIstoHire
- **言語 (language):** ja

## 概要

- 複数のAPIキーと署名付きWebhookを備えた、公開REST API
- Webサイト、フォーム、バックエンドから、HTTP呼び出し1回で顧客を登録し、すべての変更をHMAC-SHA256で署名されたかたちで自分のサーバーに受け取れます。
- 1回の呼び出しで連絡先を登録できます。メールと好きなタグを付けて `/api/apps/public/crm/customers` にPOSTすると、リードはすぐにCRMに分類されて入ります。
- 設計上、重複しません。メールがすでに存在する場合は、2枚目のカードを作る代わりに、カードを更新し、新しい送信をタイムラインに記録します。
- 名前付きのキーを最大20個。連携ごとに1つで、個別に無効化できます。キーが漏れた場合は、そのキーだけを削除すれば、他は何も止まりません。

## 複数のAPIキーと署名付きWebhookを備えた、公開REST API

AIsToHire のCRMアプリ AiCrm は、自分の連絡先に対する公開REST APIを提供します。`X-Api-Key` ヘッダーにキーを指定すれば、Webサイトのフォーム、チャットボット、Zap、Pythonスクリプト、自社のバックエンドから、連絡先の作成、一覧取得、参照、更新、削除ができ、どの連絡先にもアクティビティを追加できます。レスポンスは `{ success, data }` の形式のJSONで、上限はキーごとに1分あたり100リクエストです。

APIからの登録は重複しません。送信したメールがすでにデータベースにある場合、AiCrm はすでにあるカードを更新し(足りない電話番号、名前、会社を補い、タグを結合)、新しい送信をタイムラインに記録して、HTTP 200を返します。新規の場合は作成して201を返します。APIで入ってきた連絡先には、自動的に `api-lead` のタグが付き、送信したタグはそのまま保持され、流入元の `subId` と、アクセス元の国、IP、ブラウザが保存されます。

名前付きのAPIキーは、アプリ内部のキーに加えて、最大20個まで作成できます。連携ごと(Webサイト、5月のキャンペーンのフォーム、インターン、取引先)に別のキーを渡し、その連携が終わったら、他に触れずにそのキーだけを無効化できます。キーの完全な値は、作成時に一度だけ表示され、その後は一覧でマスクされた状態でしか見られません。

逆方向では、Webhookがシステムに通知します。最大10の宛先を設定し、それぞれが購読するイベント(`customer.created`、`customer.updated`、`customer.deleted`、`activity.created`)を選ぶと、AiCrm が `X-AiCrm-Event` と `X-AiCrm-Signature: sha256=…` のヘッダーを付けて、あなたのURLにPOSTします。後者は、そのWebhookのシークレットで計算した本文の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` のドメインが拒否されます。

## 含まれる機能

- 1回の呼び出しで連絡先を登録できます。メールと好きなタグを付けて `/api/apps/public/crm/customers` にPOSTすると、リードはすぐにCRMに分類されて入ります。
- 設計上、重複しません。メールがすでに存在する場合は、2枚目のカードを作る代わりに、カードを更新し、新しい送信をタイムラインに記録します。
- 名前付きのキーを最大20個。連携ごとに1つで、個別に無効化できます。キーが漏れた場合は、そのキーだけを削除すれば、他は何も止まりません。
- HMAC-SHA256で署名されたWebhook。自分のシークレットで `X-AiCrm-Signature` ヘッダーを検証すれば、通知が第三者ではなく自分のCRMから来たと分かります。
- SSRF対策が最初から入っています。アプリは、localhostやプライベートネットワークの範囲へのWebhook配信を拒否するので、CRMを内部ネットワークの探索に使われることはありません。
- 登録だけでなく、CRUDを完全にサポート。ページネーションとフィルター(検索、ステータス、タグ、国)つきの一覧、アクティビティを含む連絡先の取得、更新、削除、アクティビティの記録ができます。
- 流入元を自動で追跡します。API経由の登録ごとに、送信した `subId` に加えて、国、IP、ブラウザが保存され、`api-lead` のタグが付くので、あとでアプリ内で絞り込めます。
- 当て推量なしでテストできます。アプリには、コピーできる `curl` の例つきのエンドポイントのドキュメントがあり、各Webhookにテスト配信を送るボタンと、最後の試行のステータスと時刻も表示されます。

## よくある質問

### 自分のWebサイトから、CRMに連絡先を作成するには?

`X-Api-Key` ヘッダーを付けて、少なくともメールまたは電話番号を含むJSONを `/api/apps/public/crm/customers` にPOSTします。名前、電話番号、会社、国、ステータス、メモ、タグ、そして元のキャンペーンやフォームを識別する `subId` も送れます。AiCrm は、作成した場合は201を、その連絡先がすでに存在していた場合は200を返します。

### 同じメールがAPIから2回入ってきたらどうなりますか?

重複しません。AiCrm はメール(メールがない場合は電話番号)を探し、見つかれば、既存のカードの空の項目を埋めて更新し、新しいタグをすでにあるタグと結合し、新しい送信をアクティビティのタイムラインに記録します。レスポンスは、その連絡先がすでに存在していたことを示し、そのidを返します。

### APIキーはいくつ持てますか? 1つだけ無効化できますか?

アプリ内部のキー(削除できません)に加えて、独自の名前を付けたキーを最大20個作成できます。各キーは個別に削除できるので、連携ごとに別のキーを渡し、他に影響を与えず無効化できます。完全な値は作成時にだけ表示され、その後は一覧でマスクされます。すべてのキーは、キーごとに1分あたり100リクエストという上限を共有します。

### Webhookが本当に自分のCRMから来たものかどうかを確認するには?

各配信には、`X-AiCrm-Signature: sha256=<firma>` というヘッダーが付きます。これは、Webhookの作成時にアプリが表示するシークレットを使った、リクエスト本文そのもののHMAC-SHA256です。自分のサーバーで、受け取った本文に対してこのHMACを計算し、比較してください。さらに、イベント名を示す `X-AiCrm-Event` ヘッダーも送られます。`customer.created`、`customer.updated`、`customer.deleted`、`activity.created` のいずれかです。

### Webhookのエンドポイントが落ちているとどうなりますか?

配信はベストエフォートです。AiCrm は最大5秒待ち、失敗した場合は1.5秒後に1回だけ再試行します。永続的な再試行キューはないので、サーバーが長時間ダウンすると通知を失う可能性があります。その場合は、`/api/apps/public/crm/customers` へのGETで照合してください。アプリには各Webhookの最後の試行のステータスと時刻が表示され、テスト配信はいつでも実行できます。

- [AiCrm — どんなシステムからも顧客を登録できるAPI付き軽量CRM](https://aistohire.com/ja/aicrm-lightweight-crm-with-api-109)

## プラットフォームについて

**AiCrm — どんなシステムからも顧客を登録できるAPI付き軽量CRM** — のアプリ AIstoHire. 対応言語: https://aistohire.com/ja/aicrm-lightweight-crm-with-api-109/f/crm-rest-api-signed-webhooks

### その他の言語

- `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
- `nl`: https://aistohire.com/nl/aicrm-eenvoudige-crm-met-api-om-klanten-en-leads-te-beheren-109/f/rest-api-crm-ondertekende-webhooks
- `ko`: https://aistohire.com/ko/aicrm-api-gyeongnyang-crm-109/f/crm-rest-api-seomyeong-webhook
- `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
