Webhooks | Centre d'aide Sellsy

Sellsy propose un système de webhook pour optimiser la liaison avec vos solutions.

Lors d’un évènement côté Sellsy (création client, mise à jour document) nous vous donnons la possibilité de déclencher l’envoi d’information de Sellsy vers une URL à configurer par vos soins (à vous de traiter ces données à réception).

Actuellement, 2 types de webhooks existent via Sellsy :

Webhook Slack,
Webhook HTTP.

Qui doit mettre en place le webhook sur Sellsy

Seul un administrateur du compte Sellsy peut configurer les webhooks. Il s’agit de manipulations sensibles, tant d’un point de vue technique, que sur le plan de la confidentialité des données.

Configuration du webhook sur Sellsy

Rendez-vous dans "Menu" > "Réglages" > "Portail développeurs" et cliquez sur “Webhooks”.

Ensuite, choisissez le webhook à configurer.

Configurer un webhook Slack

La configuration sur Slack demande aussi d’être administrateur du compte Slack.

Vous devez :

Créer l’url du webhook sur Slack,
Finaliser la configuration sur Sellsy.

Créer l’url du Webhook Slack

Connectez-vous à votre compte Slack.
Accédez à l’adresse suivante : https://my.slack.com/services/new/incoming-webhook/
Vous allez être redirigé vers une URL du type https://votre_pseudo.slack.com/apps/new/XXXXXXXX-incoming-webhooks

Choisissez un channel par défaut (cette valeur est obligatoire pour valider l’ajout sur Slack, mais elle sera surchargée sur Sellsy). Exemple : channel “#general” ci-dessous.

Cliquez sur “Add Incoming WehHooks integration”.
Vous allez ensuite obtenir le “Webhook URL” à utiliser sur Sellsy.

Bon à savoir : vous retrouverez la documentation technique sur le webhook Slack ici.

Finaliser la configuration Slack sur Sellsy

Copiez le “Webhook URL” récupéré à l’étape précédente puis collez-le sur Sellsy (champ nommé “Endpoint Slack”).

Inscrivez le nom channel Slack par défaut (qui va surcharger la valeur de l’étape ci-dessus).
Choisissez ensuite d’activer ou non l’envoi des données sur Slack.
Concernant les informations envoyées au Webhook, vous pouvez choisir un “Channel” propre à chaque action.

Webhook HTTP

Vous devez ajouter l’URL vers votre script dans la section nommée : Configurer le webhook.
Puis “Endpoint personnalisé”.
Activez le webhook (cochez la case en face de “Webhook Actif ?”).
Sélectionnez les actions sur lesquelles vous souhaitez obtenir un retour via le webhook.

Informations utiles sur le format de retour du webhook :

Un exemple vous permettant de récupérer le contenu POST envoyé par le webhook en PHP,
Le contenu du “form-urlencoded” envoyé par le webhook,
La liste des types d’objets renvoyé (relatedtype),
Le webhook n’attends pas de réponse,
Le webhook ne gère pas les erreurs.

Options avancées

Signature des webhooks.

Les webhooks sont signés afin de garantir leur intégrité.

Un en-tête HTTP X-Webhook-Signature est ajouté à chaque requête, contenant la valeur suivante : `SHA1(SIGN_KEY + WEBHOOK_BODY)`

La clé de signature (`SIGN_KEY`) est disponible et personnalisable depuis le formulaire de création du webhook.

Exemple en php

<?php 

// Corps brut de la requête (body reçu tel quel) 

$body = file_get_contents('php://input'); 

// Signature calculée 

$expectedSignature = sha1('ma_clé_secrète' . $body); 

// Vérification 

$webhookIsValid = hash_equals($expectedSignature, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'])

Liste des objets (related types) :

$related = [

'staff', ## staff member

'third', ## company: client,prospect,supplier

'people', ## contact

'item', ## catalog item or service

'import', ## import

'purinvoice', ## purchase supplier invoice

'purdeliery', ## purchase supplier delivery

'purorder', ## purchase supplier order

'purcredinote', ## purchase supplier credit note

'timetracking', ## timetracking entry

'opportunity', ## prospection opportunity

'ticket', ## support ticket

'project', ## project

'expense', ## expense

'rent', ## rental : rent or book

'campaignemail', ## email marketing campaing

'campaignsms', ## sms marketing campaign

'proptemplate', ## proposale template

'propdocument', ## proposal

'estimate', ## sale estimate

'invoice', ## sale invoice

'delivery', ## sale delivery

'order', ## sale order

'proforma', ## sale proforma invoice

'model' ## sale model

];

Ressources complémentaires

Pour en savoir plus sur les webhooks :

Documentation technique générale : https://en.wikipedia.org/wiki/Webhook (en anglais)
Documentation Slack Incoming Webhooks : https://api.slack.com/incoming-webhooks
Article sur l'API Sellsy : API V2