API

Webhooks

Un webhook est une requête HTTP que FoodSoul envoie à l'adresse de votre système lorsqu'un événement se produit dans le compte : nouvelle commande, changement de statut, avis, et autres.

L’abonnement avec adresse et événements est créé par la méthode :

POST Créer un abonnement au webhook

L'adresse est l'URL de l'abonnement, la méthode est POST.

Format, signature et répétitions

Corps de la requête webhook. Chaque requête est un POST avec Content-Type: application/json vers l’URL de souscription. L’URL doit commencer par https.
En-têtes : X-Webhook-Event — code de l’événement, X-Webhook-ID — event_uuid, X-Webhook-Signature — sha256= suivi du HMAC-SHA256 du corps brut de la requête en hex avec le secret de la filiale (webhooks_subscriptions.generate_secret).
Vérifiez la signature sur le corps brut avant l’analyse du JSON : hash_equals(hash_hmac('sha256', $body, $secret), substr($signature, 7)). Il n’y a pas d’horodatage dans la signature, le canal est protégé par HTTPS.
La livraison est considérée comme acceptée pour toute réponse 2xx reçue dans les 10 secondes. Les redirections ne sont pas suivies. Sinon, la livraison est retentée : 7 tentatives, la première immédiatement, puis après 1, 5, 15, 60, 180 et 360 minutes. Toutes les tentatives d’une même livraison contiennent le même X-Webhook-ID. Une réexpédition depuis le journal (webhooks_logs.resend) utilise le même X-Webhook-ID — ignorez les livraisons déjà traitées selon cet identifiant.
20 échecs consécutifs désactivent la souscription (blocked), et le propriétaire ainsi que l’administrateur système du compte reçoivent un e-mail. webhooks_subscriptions.unblock réactive la souscription.
Le corps contient les données de l’événement : le client, l’avis et la fiche de commande sont transmis intégralement. Le solde de bonus n’est pas transmis : il est commun au pool de réseaux et doit être obtenu via l’API.

En-têtes

X-Webhook-Eventstringobligatoire

Exemple: order.created

X-Webhook-IDstringobligatoire

Exemple: 5f0c6b1e-6a1d-4c1e-9d6b-3a7f0e2b8c41

X-Webhook-Signaturestringobligatoire

Exemple: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Événements

  • client.registered
  • client.updated
  • client.bonuses_changed
  • order.created
  • order.status_changed
  • order.payment_status_changed
  • feedback.created
  • courier.assigned
  • item.stop_list_changed
  • branch.work_status_changed

Corps de la requête

object (WebhookPayload)
eventstringobligatoire

Valeurs:client.registeredclient.updatedclient.bonuses_changedorder.createdorder.status_changedorder.payment_status_changedfeedback.createdcourier.assigneditem.stop_list_changedbranch.work_status_changed

Exemple: order.status_changed

event_uuidstringobligatoire

Exemple: 5f0c6b1e-6a1d-4c1e-9d6b-3a7f0e2b8c41

date_creationstring (DataTimeFormatSQL) obligatoire

Exemple: 2024-05-02 08:31:16

branch_idintegerobligatoire

Exemple: 8412

dataoneOfobligatoire
L'une des options
object (WebhookDataClientRegistered)

client.registered — nouveau numéro de téléphone ou première connexion du compte dans cette succursale

client_branch_profile_idintegerobligatoire

Exemple: 730112

namestringpeut être nul

Exemple: John Doe

phonestringobligatoire

Numéro de téléphone au format international, sans mise en forme

Exemple: +79114579423

genderstringpeut être nul

Valeurs:womanman

Exemple: man

date_of_birthstringpeut être nul

Date de naissance au format Y-m-d

Exemple: 1982-01-03

Exemple de corps

{
  "event": "order.status_changed",
  "event_uuid": "5f0c6b1e-6a1d-4c1e-9d6b-3a7f0e2b8c41",
  "date_creation": "2024-05-02 08:31:16",
  "branch_id": 8412,
  "data": {
    "client_branch_profile_id": 730112,
    "name": "John Doe",
    "phone": "+79114579423",
    "gender": "man",
    "date_of_birth": "1982-01-03"
  }
}

Réponse de votre système

2XX

Accepté

default

Не принято, доставка повторяется