Aller au contenu

Développeurs

API REST et webhooks

Lisez et écrivez chaque fiche de votre espace de travail depuis vos propres scripts et outils, et soyez averti quand les choses changent. L’API et les webhooks sont disponibles avec Starter, Pro et Business.
Sur cette page

Authentification

Créez une clé dans Paramètres → API et webhooks. Les clés commencent par grw_ et ne sont affichées qu’une fois : conservez la vôtre en lieu sûr. Une clé agit comme l’utilisateur qui l’a créée, avec le rôle de cet utilisateur, dans cet espace de travail. Révoquez-la depuis la même page.

Envoyez la clé comme jeton porteur. L’URL de base est https://growlyne.com :

curl https://growlyne.com/api/v1/me \
  -H "Authorization: Bearer grw_your_key"

Utilisateurs en lecture seule

Les clés des lecteurs peuvent lire mais pas écrire : toute écriture renvoie 403.

Points d’accès

:object est la clé d’un objet : contacts, companies, deals, tickets, ou la clé d’un objet personnalisé. GET /api/v1/objects les liste tous avec leurs clés de propriétés.

MéthodeCheminRôle
GET/api/v1/meL’utilisateur, le rôle et l’espace de travail de la clé
GET/api/v1/objectsLes objets, leurs propriétés et leurs pipelines, ainsi que les utilisateurs de l’espace de travail
GET/api/v1/records/:objectLister les fiches. Paramètres : limit, offset, search, filters (JSON), sort=prop:asc|desc, listId
GET/api/v1/records/:object/:idUne fiche avec ses associations, ses tâches et ses e-mails
POST/api/v1/records/:objectCréer une fiche : { values, associate? }
PATCH/api/v1/records/:object/:idModifier une fiche : { values }
DELETE/api/v1/records/:object/:idArchiver une fiche
POST/api/v1/records/:object/:id/notesAjouter une note à l’historique : { body, subject? }
GET/api/v1/tasksVos tâches en cours
POST/api/v1/opsExécuter n’importe quelle opération utilisée par l’application : { op, args }

Exemples

Créer un contact

curl -X POST https://growlyne.com/api/v1/records/contacts \
  -H "Authorization: Bearer grw_your_key" \
  -H "content-type: application/json" \
  -d '{ "values": { "email": "sam@example.com", "firstname": "Sam" } }'

Rechercher des affaires, les plus récentes d’abord

curl "https://growlyne.com/api/v1/records/deals?search=renewal&sort=createdAt:desc&limit=50" \
  -H "Authorization: Bearer grw_your_key"

Ajouter une note à une fiche

curl -X POST https://growlyne.com/api/v1/records/contacts/REC_ID/notes \
  -H "Authorization: Bearer grw_your_key" \
  -H "content-type: application/json" \
  -d '{ "subject": "Call", "body": "Discussed the Q1 rollout." }'

Exécuter une opération

POST /api/v1/ops expose les opérations que l’application utilise elle-même, comme record.merge, record.associate, record.bulkUpdate ou task.upsert. Un nom inconnu renvoie 400 avec la liste des opérations disponibles.

curl -X POST https://growlyne.com/api/v1/ops \
  -H "Authorization: Bearer grw_your_key" \
  -H "content-type: application/json" \
  -d '{ "op": "record.merge", "args": { … } }'

Les clés de propriétés dépendent de votre espace de travail : lisez-les avec GET /api/v1/objects avant d’écrire.

Réponses, erreurs et limites

Les réponses réussies sont du JSON de la forme { "data": … }. Les erreurs sont de la forme { "error": "message" }, avec le statut correspondant :

StatutSignification
400Entrée invalide, ou opération inconnue
401Clé absente ou invalide
402L’offre de l’espace de travail n’inclut pas l’API
403Votre rôle ne l’autorise pas
404Route ou fiche introuvable
429Limite de débit atteinte

La limite de débit est de 600 requêtes par minute et par utilisateur.

Webhooks

Les administrateurs de l’espace de travail ajoutent des webhooks dans Paramètres → API et webhooks : une URL HTTPS et les événements à recevoir. Les workflows peuvent aussi appeler un webhook parmi leurs actions.

Événements :

ÉvénementQuand
record.createdUn contact, une entreprise, une affaire, un ticket ou une fiche personnalisée est créé (application, API, formulaire, import, boîte de réception)
record.updatedUne propriété change. Le corps contient la fiche et la liste des modifications
record.deletedUne fiche est supprimée définitivement
deal.stage_changedUne affaire passe à une autre étape, avec les identifiants de l’ancienne et de la nouvelle étape
form.submittedQuelqu’un envoie l’un de vos formulaires

Chaque envoi est un POST avec un corps JSON { "event", "data", "sentAt" } et ces en-têtes :

En-têteValeur
growlyne-eventLe nom de l’événement
growlyne-deliveryUn identifiant unique pour cet envoi, pratique pour ignorer les répétitions
growlyne-signatureHMAC-SHA256 hexadécimal du corps brut, calculé avec le secret du webhook

Vérifiez la signature avant de faire confiance à une charge utile :

import { createHmac, timingSafeEqual } from "node:crypto";

const expected = createHmac("sha256", process.env.GROWLYNE_WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["growlyne-signature"]));

Répondez avec n’importe quel code 2xx en moins de 10 secondes. Un envoi échoué (erreur réseau, délai dépassé ou autre statut) est retenté jusqu’à 5 fois avec des délais croissants, et les envois récents sont listés dans les paramètres avec leur statut.