API en webhooks

Met API en webhooks werken uw eigen systemen (ERP, datawarehouse, website-backend, automatiseringstools) samen met uw NextCRM-workspace:

• de REST-API leest en wijzigt leads, contacten, taken en notities, en leest funnels, formulierinzendingen, campagnes en teamleden;
• webhooks waarschuwen uw server zodra er iets gebeurt, bijvoorbeeld een nieuwe lead of een fasewissel.

Opmerking: Alleen Workspace-beheerders kunnen Instellingen > API en webhooks openen. API-toegang zit in de abonnementen Business, Agency en Enterprise. Bij andere abonnementen blijven bestaande sleutels en endpoints zichtbaar, maar kunnen er geen nieuwe worden aangemaakt en worden API-aanroepen geweigerd.

Waar u elke waarde vindt

Alles komt uit NextCRM zelf; u hebt geen account bij een derde partij nodig.

Waarde	Waar u het vindt
API-sleutel	Instellingen > API en webhooks > API-sleutel aanmaken. De volledige sleutel wordt maar één keer getoond; kopieer hem als Bearer-token naar uw koppeling (bijvoorbeeld n8n, Zapier, Make of uw eigen code).
Ondertekeningsgeheim	Wordt één keer getoond wanneer u een webhook-endpoint toevoegt, en opnieuw na Geheim vernieuwen. Bewaar het op de server die de webhooks ontvangt.
Endpoint-URL	Komt uit uw eigen systeem of automatiseringstool, bijvoorbeeld de productie-URL van een n8n Webhook-node. Hij moet https gebruiken.

Volgorde van instellen: maak een API-sleutel met de rechten die u nodig hebt > doe een eerste aanroep > voeg een webhook-endpoint met de gewenste gebeurtenissen toe > controleer de handtekening op uw server > stuur een testgebeurtenis.

Een API-sleutel maken

1. Klik op uw profielkaart onderaan de zijbalk, kies Instellingen en open de kaart API en webhooks (API en webhooks openen) en blijf op het tabblad API-sleutels.
2. Klik op API-sleutel aanmaken.
3. Voer een Naam in waaraan u ziet waar de sleutel wordt gebruikt, bijvoorbeeld "ERP-synchronisatie".
4. Kies onder Rechten per onderdeel Lezen en/of Schrijven. Kies alleen wat de koppeling echt nodig heeft.
5. Stel eventueel een vervaldatum in onder Verloopt (30, 90 of 365 dagen, of een datum).
6. Klik op Sleutel aanmaken en kopieer de sleutel meteen met Kopiëren.

Waarschuwing: De sleutel wordt maar één keer getoond. NextCRM bewaart alleen een vingerafdruk (hash), dus niemand - ook support niet - kan hem opnieuw tonen. Bent u hem kwijt, trek hem dan in en maak een nieuwe aan.

De lijst toont elke sleutel met zijn voorvoegsel (bijvoorbeeld ncrm_live_1a2b3c4d), de rechten, wie hem heeft gemaakt, wanneer hij voor het laatst is gebruikt en wanneer hij verloopt. Intrekken blokkeert een sleutel direct.

Wat een sleutel mag

Een sleutel handelt namens uw workspace met de rechten van een Workspace-beheerder, beperkt tot de gekozen rechten:

Recht	Staat toe
Leads (lezen / schrijven)	Leads tonen en lezen; aanmaken, wijzigen, naar een fase verplaatsen, toewijzen, naar de prullenbak verplaatsen en terugzetten
Contacten (lezen / schrijven)	Contacten tonen, lezen, aanmaken, wijzigen en verwijderen
Taken (lezen / schrijven)	Taken tonen en lezen; aanmaken, wijzigen, afronden en archiveren
Funnels en fases (lezen)	Funnels met hun fases lezen
Formulierinzendingen (lezen)	Formulieren en hun inzendingen lezen
Campagnes (lezen)	Campagnes en hun resultaten lezen
Notities en activiteiten (lezen / schrijven)	Notities en tijdlijn van een lead lezen; notities toevoegen en gesprekken vastleggen
Teamleden (lezen)	Namen, e-mails en rollen van teamleden lezen (om leads en taken toe te wijzen)
Webhooks (lezen / schrijven)	Webhook-endpoints lezen, registreren en verwijderen

Dezelfde regels gelden als in de app: abonnementslimieten (een nieuwe lead boven uw limiet voor actieve leads komt in de Lead Inbox), de prullenbak (leads in de prullenbak moeten eerst worden teruggezet; verwijderen via de API verplaatst altijd naar de prullenbak) en gegevens komen nooit in een andere workspace terecht. Wat alleen mensen mogen - team, rollen, facturatie of API-sleutels beheren en definitief verwijderen - kan niet met een sleutel. Een sleutel werkt ook niet meer wanneer degene die hem heeft gemaakt geen Workspace-beheerder meer is.

Elke wijziging met een sleutel verschijnt in de tijdlijn van de lead als API key <naam>.

Uw eerste aanroep

Stuur de sleutel in de header Authorization. De basis-URL is https://…/api/v1.

curl https://…/api/v1/leads?limit=10 \
  -H "Authorization: Bearer ncrm_live_..."

Een lead aanmaken:

curl -X POST https://…/api/v1/leads \
  -H "Authorization: Bearer ncrm_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2a10-order-4711" \
  -d '{"first_name":"Ada","last_name":"Lovelace","email":"ada@example.com","value":12000}'

De volledige referentie met alle endpoints, velden en een curl-voorbeeld staat op het tabblad API-documentatie, openbaar op https://…/api/v1/docs en als OpenAPI 3.1-bestand op https://…/api/v1/openapi.json.

Regels voor elke koppeling

• Antwoorden hebben de vorm { "data": ..., "meta": { ... } }, fouten { "error": { "code", "message", "details" } } met een veldenlijst bij validatiefouten. Datums zijn ISO 8601 in UTC.
• Paginering: lijsten geven meta.next_cursor terug; geef die mee als cursor voor de volgende pagina (limit tot 100).
• Idempotentie: stuur een Idempotency-Key-header mee met POST-verzoeken. Een herhaling met dezelfde sleutel geeft het eerste resultaat terug in plaats van een dubbel record (24 uur lang).
• Limieten: 120 verzoeken per minuut per sleutel en 600 per workspace. Daarboven antwoordt de API met 429 en een Retry-After-header: wacht zoveel seconden.
• Onderhoud: tijdens een NextCRM-update antwoordt de API met 503 MAINTENANCE en Retry-After. Webhooks worden vastgehouden en daarna afgeleverd.
• Alleen vanaf de server: roep de API aan vanaf uw server. Browsers kunnen hem niet aanroepen (geen CORS) en een API-sleutel hoort nooit in een website of app.

Webhooks

1. Open het tabblad Webhooks en klik op Endpoint toevoegen.
2. Voer de Endpoint-URL van uw server in. Die moet met https:// beginnen en bereikbaar zijn via internet; interne, privé- en cloud-metadata-adressen worden geweigerd.
3. Kies de gewenste Gebeurtenissen en klik op Endpoint opslaan.
4. Kopieer het ondertekeningsgeheim (één keer getoond) en bewaar het op uw server.
5. Klik op Testgebeurtenis sturen om te controleren of uw server antwoordt.

Beschikbare gebeurtenissen: lead.created, lead.updated, lead.stage_changed, lead.assigned, lead.trashed, lead.restored, task.created, task.completed, form.submitted, contact.created, contact.updated, campaign.sent, call.logged, nps.responded, customer.renewal_updated, customer.at_risk, booking.created, booking.rescheduled, booking.canceled, quote.sent, quote.accepted, quote.declined en automation.webhook.

Offerte-gebeurtenissen bevatten bedragen als gehele getallen in de kleinste eenheid van de valuta (bijvoorbeeld centen): subtotal_minor is de som van de regels na regelkortingen, discount_minor de korting op de hele offerte, tax_minor de btw en total_minor het te betalen bedrag. De total_minor van een regel is het bedrag na de regelkorting, vóór de offertekorting en de btw.

Leads uit een bestandsimport sturen na afloop van de import één lead.created per geïmporteerde lead, met "context": { "source": "import", "import_batch_id": "..." } naast data.

Elke levering is een POST met de gebeurtenis als JSON (id, type, created_at, actor, data) en deze headers: X-NextCRM-Event, X-NextCRM-Delivery, X-NextCRM-Timestamp en X-NextCRM-Signature.

De handtekening controleren

X-NextCRM-Signature ziet eruit als t=1760860800,v1=5f2b.... Bereken HMAC-SHA256 van <t>.<ruwe request-body> met uw ondertekeningsgeheim en vergelijk het met v1. Weiger verzoeken waarvan de tijdstempel ouder is dan 5 minuten.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const t = Number(/(?:^|,)t=(\d+)/.exec(header)?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return header.split(",").some((part) => part === `v1=${expected}`);
}

Herhalingen, leveringslogboek en vernieuwen

• Antwoord binnen 10 seconden met een willekeurige 2xx-status. Anders probeert NextCRM het opnieuw met steeds langere pauzes (1, 2, 4, ... minuten), tot 8 pogingen.
• Het Leveringslogboek toont elke levering met status, pogingen en antwoordcode. Opnieuw sturen plant een levering nog een keer in.
• Na veel mislukkingen op rij wordt een endpoint automatisch uitgeschakeld en krijgen alle Workspace-beheerders een melding. Herstel het endpoint en klik dan op Inschakelen.
• Geheim vernieuwen maakt een nieuw ondertekeningsgeheim. Het oude blijft 24 uur meetekenen, zodat u kunt overstappen zonder gebeurtenissen te missen.

Lora en de API

Lora kan de API uitleggen, deze pagina openen en uw webhook-endpoints tonen. Ze maakt, toont of trekt nooit API-sleutels in en ziet nooit een ondertekeningsgeheim - dat doet u zelf op deze pagina.

Problemen oplossen

Antwoord	Betekenis
401 INVALID_API_KEY, API_KEY_REVOKED, API_KEY_EXPIRED	De sleutel is onjuist, ingetrokken of verlopen. Maak een nieuwe.
403 INSUFFICIENT_SCOPE	De sleutel mist het recht voor deze aanroep. Maak een sleutel met het benodigde recht.
403 API_KEY_OWNER_NOT_ADMIN	Degene die de sleutel maakte is geen Workspace-beheerder meer. Een huidige beheerder moet een nieuwe sleutel maken.
402 FEATURE_NOT_IN_PLAN	Het abonnement bevat geen API-toegang.
409 LEAD_IN_TRASH	Zet de lead eerst terug (POST /leads/{id}/restore).
422 VALIDATION_FAILED	Het veld en de reden staan in error.details.
429 RATE_LIMITED	Wacht de Retry-After-seconden en ga dan verder.