# REST API for CRM with signed webhooks | AiCrm

> Public REST API CRM: create and query customers with an X-Api-Key HTTP header, up to 20 keys per integration, and outgoing webhooks signed with HMAC-SHA256. Lead registration from your website without duplicates.

- **Source (source):** https://aistohire.com/aicrm-lightweight-crm-with-api-109/f/api-rest-crm-signed-webhooks
- **Platform (platform):** AIstoHire
- **Language (language):** en

## In summary

- Public REST API with multiple API keys and signed webhooks
- Register customers from your website, form, or backend with an HTTP call, and receive every change on your server signed with HMAC-SHA256.
- Customer registration with a single call
- No duplicates by design
- Up to 20 named API keys

## Public REST API with multiple API keys and signed webhooks

AiCrm, the CRM app from AIsToHire, exposes a public REST API over your own customers. With an API key in the `X-Api-Key` HTTP header, you can create, list, query, update, and delete customers, and add activities to any of them, from your website form, chatbot, a Zap, a Python script, or your own backend. Responses are JSON in the format `{ success, data }`, and the limit is 100 requests per minute per key.

API registration does not duplicate: if the email you send already exists in your database, AiCrm updates the existing customer record (completes missing phone, name, or company, merges the tags/labels) and logs a new submission in its timeline, returning HTTP 200; if it's new, it creates it and returns 201. Each customer entering via API is automatically tagged as `api-lead`, retains the tags/labels you send, and saves the source `subId`, in addition to the country, IP, and browser from which they arrived.

You can have up to 20 named API keys, in addition to the app's internal key. This way, you give a different key to each integration —the website, the May campaign form, the intern, the vendor— and revoke it individually when that integration ends, without affecting the others. The full value of a key is shown only once, upon creation; afterwards, it is only visible masked in the list.

In the other direction, webhooks notify your systems. You configure up to 10 destinations, choose which events each subscribes to (`customer.created`, `customer.updated`, `customer.deleted`, `activity.created`), and AiCrm performs a POST to your URL with the `X-AiCrm-Event` and `X-AiCrm-Signature: sha256=…` HTTP headers, the HMAC-SHA256 signature of the body with that webhook's secret, so you can verify that the delivery is legitimate. When saving the URL, an anti-SSRF guard rejects localhost, 127.0.0.0/8, 10.x, 192.168.x, 172.16-31.x, ::1, 0.0.0.0, and `.local` and `.internal` domains.

## What's included

- **Customer registration with a single call** — a POST to `/api/apps/public/crm/customers` with the email and any tags/labels you want, and the lead is already classified in your CRM.
- **No duplicates by design** — if the email already exists, the customer record is updated and the new submission is logged in its timeline instead of creating a second record.
- **Up to 20 named API keys** — one per integration, separately revocable. If a key is leaked, you delete only that one, and nothing else stops working.
- **Webhooks signed with HMAC-SHA256** — verify the `X-AiCrm-Signature` HTTP header with your secret to confirm the notification originates from your CRM, not a third party.
- **Anti-SSRF protection included** — the app refuses to deliver webhooks to localhost or private network ranges, preventing your CRM from being used to probe an internal network.
- **Full CRUD, not just creation** — list with pagination and filters (search, lifecycle status, contact tags, country), query a customer with their activity, update, delete, and log activities for them.
- **Automatically traced origin** — each API creation saves the `subId` you send, plus the country, IP, and browser, and is tagged as `api-lead` for later filtering in the app.
- **Guesswork-free testing** — the app includes endpoint documentation with a copyable `curl` example and a button to send a test delivery to each webhook, showing the lifecycle status and time of the last attempt.

## Frequently Asked Questions

### How do I create a customer in the CRM from my website?

You make a POST request to `/api/apps/public/crm/customers` with the `X-Api-Key` header and a JSON payload containing at least the email or phone number. You can also send the name, phone, company, country, status, notes, tags, and a `subId` to identify the originating campaign or form. AiCrm returns 201 if it creates the customer and 200 if that customer already existed.

### What happens if the same email is submitted twice via the API?

It is not duplicated. AiCrm searches for the email (or phone number, if no email is provided) and, if found, updates the existing record by filling in any empty fields, merges new tags with existing ones, and logs the new submission in its activity timeline. The response indicates that the customer already existed and returns its ID.

### How many API keys can I have and can I revoke a single one?

You can create up to 20 named keys, in addition to the app’s internal key, which cannot be deleted. Each key is deleted independently, so you can give a different one to each integration and revoke it without affecting the others. The full value is shown only at the time of creation; afterwards, it appears masked in the list. All keys share the limit of 100 requests per minute per key.

### How do I verify that a webhook truly comes from my CRM?

Each delivery carries the HTTP header `X-AiCrm-Signature: sha256=<signature>`, which is the HMAC-SHA256 of the exact request body using the secret the app shows you when creating the webhook. Calculate that HMAC on your server over the received body and compare it. The `X-AiCrm-Event` HTTP header also travels with the event name: `customer.created`, `customer.updated`, `customer.deleted`, or `activity.created`.

### What happens if my webhook endpoint is down?

The delivery is best-effort: AiCrm waits up to 5 seconds and, if it fails, retries after one and a half seconds. There is no persistent retry queue, so a long server downtime can cause you to lose notifications; in that case, reconcile with a GET to `/api/apps/public/crm/customers`. The app shows you the lifecycle status and time of the last attempt for each webhook, and you can launch a test delivery whenever you want.

- [AiCrm — Lightweight CRM with API to create customers from any system](https://aistohire.com/aicrm-lightweight-crm-with-api-109)

## About the platform

**AiCrm — Lightweight CRM with API to create customers from any system** — an app by AIstoHire. Available at: https://aistohire.com/aicrm-lightweight-crm-with-api-109/f/api-rest-crm-signed-webhooks

### Other languages

- `es`: https://aistohire.com/es/aicrm-crm-ligero-con-api-109/f/api-rest-crm-webhooks-firmados
- `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
- `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
