Webhooks

Les webhooks sont là pour informer votre système des événements qui surviennent lors de la livraison. Ils vous permettent de les exploiter, par exemple pour informer votre acheteur et/ou votre vendeur de l'avancée de la livraison.

Définir des webhooks

info

Les webhooks se définissent dans votre compte client > Webhook

Webhooks disponibles

concernant les annonces

Evénement	Paramètres	Correspondance	Commentaire
ride_published	voir détails	Annonce créée	Cocolis publie l’annonce. Les transporteurs sont informés.
ride_availabilities_pending	voir détails	Annonce en attente de confirmation de disponibilités	Un transporteur s'est proposé sur un créneau de livraison. Il nous manque la confirmation de disponibilité de l'expéditeur et du destinataire.
ride_started	voir détails	Annonce en cours de livraison	Un transporteur est prêt à effectué la livraison.
ride_expired	voir détails	Annonce expirée	L'annonce n'a pas trouvé de transporteur. Se rapprocher de notre support.
ride_completed	voir détails	Annonce complétée	L'objet de l'annonce a été remis à son destinataire
ride_moderated	voir détails	Annonce modérée	L'annonce a été modéré par notre équipe car ne respectant pas nos conditions. Se rapprocher de notre support.
ride_removed	voir détails	Annonce supprimée	L'annonce a été supprimée.

concernant les offres

Evénement	Paramètres	Correspondance	Commentaire
offer_accepted	voir détails	Un porteur a été sélectionné pour réaliser la livraison	Le transporteur livrera aux créneaux qu'il a proposé et que l'expéditeur et le destinataire ont confirmé. Cocolis affiche les coordonnées du transporteur sur les pages de tracking de l'annonce. Cocolis transmet les informations de livraison au transporteur.
offer_cancelled	voir détails	La livraison a été annulée	La livraison est annulée par le transporteur. L'expéditeur et le destinataire sont informés, leur page de tracking est mise à jour. L’annonce passe de nouveau dans le statut ride_published.
offer_completed	voir détails	Livraison effectuée	Vous pouvez indiquer à l'expéditeur que la livraison a été effectuée.
offer_rejected	voir détails	La livraison a été annulée	L'expéditeur ou le destinataire a rejeté une proposition de créneau de passage d'un potentiel transporteur, leur page de tracking est mise à jour. L’annonce passe de nouveau dans le statut published. Le payload contient le nombre de refus déjà enregistrés et le nombre maximum avant suppression de l'annonce pour déterminer si le prochain refus donnera lieu à une suppression de l'annonce.

concernant la livraison

Evénement	Paramètres	Correspondance	Commentaire
delivery_picked_up	voir détails	Le colis a été enlevé	Le transporteur a récupéré le colis chez l'expéditeur.
delivery_to_deliver	voir détails	Le colis va être livré dans la journée	Le transporteur est en route. La livraison est prête à être effectuée dans la journée.
delivery_cancelled	voir détails	La livraison a été annulée
delivery_completed	voir détails	La livraison a été effectuée	Le colis a été livré au destinataire.

concernant les disponibilités

Evénement	Paramètres	Correspondance	Commentaire
pickup_slot_accepted_by_sender	voir détails	L'expéditeur a confirmé sa disponibilité pour le créneau de collecte.	il nous manque maintenant celle du destinataire
deposit_slot_accepted_by_recipient	voir détails	Le destinataire a confirmé sa disponibilité pour le créneau de livraison	la livraison est prête à démarrer

Fonctionnement

A chaque évènement, nous effectuons une requête POST sur l'url que vous avez spécifiée avec les paramètres en body comme spécifié ci-dessus. Cela vous permet de suivre la livraison.

• Vous devez avoir un certificat SSL valide
• La réponse doit être un 200 en moins de 2 secondes
• Après la réception d'un événement, nous vous conseillons de faire la requête GET de la ressource (Offer ou Ride) afin de récupérer ses dernières informations

danger

Nos webhooks ont un timeout de 2 secondes. Donc vous ne devez pas faire de traitement synchrone sur nos webhooks, vous devez mettre en place un traitement asynchrone ou bien un traitement court.

Utilisation

A chaque webhook, nous vous renvoyons la valeur du external_id que vous avez spécifié quand vous avez créé votre ride afin que vous puissiez retrouver la commande associée. A partir de là, vous pouvez :

• Changer le status d'une commande
• Envoyer un email d'information à vos clients
• etc...

Détails des paramètres

Voici pour chaque événement le détail des informations envoyées à l'URL de webhook.

ride_published

{
	event: 'ride_published',
	created_at: DateTime,
	resource_id: ride_id,
	resource_type: 'ride',
	external_id: ride_external_id,
  external_description: Text,
	ride_id: ride_id
}

ride_availabilities_pending

{
	event: 'ride_availabilities_pending',
	created_at: DateTime,
	resource_id: ride_id,
	resource_type: 'ride',
	external_id: ride_external_id,
  external_description: Text,
	ride_id: ride_id
}

ride_started

{
  event: 'ride_started',
  created_at: DateTime,
  resource_id: ride_id,
  resource_type: 'ride',
  external_id: ride_external_id,
  external_description: Text,
  ride_id: ride_id
}

ride_expired

{
  event: 'ride_expired',
  created_at: DateTime,
  resource_id: ride_id,
  resource_type: 'ride',
  external_id: ride_external_id,
  external_description: Text,
  ride_id: ride_id
}

ride_completed

{
  event: 'ride_completed',
  created_at: DateTime,
  resource_id: ride_id,
  resource_type: 'ride',
  external_id: ride_external_id,
  external_description: Text,
  ride_id: ride_id
}

ride_moderated

{
  event: 'ride_moderated',
  created_at: DateTime,
  resource_id: ride_id,
  resource_type: 'ride',
  external_id: ride_external_id,
  external_description: Text,
  ride_id: ride_id
}

ride_removed

{
  event: 'ride_removed',
  created_at: DateTime,
  resource_id: ride_id,
  resource_type: 'ride',
  external_id: ride_external_id,
  external_description: Text,
  ride_id: ride_id
}

offer_accepted

{
  event: 'offer_accepted',
  created_at: DateTime,
  resource_id: offer_id,
  resource_type: 'offer',
  external_id: ride_external_id,
  external_description: Text,
  ride_id: ride_id,
  pickup_slot: {
    date: Date,
    slot: Slot (morning|afternoon|evening) # deprecated,
    start_time: DateTime,
    end_time: DateTime
  },
  deposit_slot: {
    date: Date,
    slot: Slot (morning|afternoon|evening) # deprecated,
    start_time: DateTime,
    end_time: DateTime
  }
}

offer_cancelled

{
  event: 'offer_cancelled',
  created_at: DateTime,
  resource_id: offer_id,
  resource_type: 'offer',
  external_id: ride_external_id,
  external_description: Text,
  ride_id: ride_id,
  pickup_slot: {
    date: Date,
    slot: Slot (morning|afternoon|evening) # deprecated,
    start_time: DateTime,
    end_time: DateTime
  },
  deposit_slot: {
    date: Date,
    slot: Slot (morning|afternoon|evening) # deprecated,
    start_time: DateTime,
    end_time: DateTime
  }
}

offer_completed

{
  event: 'offer_completed',
  created_at: DateTime,
  resource_id: offer_id,
  resource_type: 'offer',
  external_id: ride_external_id,
  external_description: Text,
  ride_id: ride_id,
  pickup_slot: {
    date: Date,
    slot: Slot (morning|afternoon|evening) # deprecated,
    start_time: DateTime,
    end_time: DateTime
  },
  deposit_slot: {
    date: Date,
    slot: Slot (morning|afternoon|evening) # deprecated,
    start_time: DateTime,
    end_time: DateTime
  }
}

offer_rejected

{
  event: 'offer_rejected',
  created_at: DateTime,
  resource_id: offer_id,
  resource_type: 'offer',
  external_id: ride_external_id,
  external_description: Text,
  ride_id: ride_id,
  pickup_slot: {
    date: Date,
    slot: Slot (morning|afternoon|evening) # deprecated,
    start_time: DateTime,
    end_time: DateTime
  },
  deposit_slot: {
    date: Date,
    slot: Slot (morning|afternoon|evening) # deprecated,
    start_time: DateTime,
    end_time: DateTime
  },
  reject_reason: (pickup_slot_refused|pickup_slot_answer_timeout|deposit_slot_refused|deposit_slot_answer_timeout),
  ride: {
    id: Integer,
    external_id: String,
    external_description: Text,
    pickup_slot_rejection_count: Integer,
    deposit_slot_rejection_count: Integer,
    max_pickup_slot_rejection: Integer,
    max_deposit_slot_rejection: Integer,
  }
}

delivery_to_deliver

{
  event: 'delivery_to_deliver',
  created_at: DateTime,
  resource_id: delivery_id,
  resource_type: 'delivery',
  ride_id: ride_id,
  data: {
    offer_id: offer_id,
    state: String (picked_up | to_deliver | completed | cancelled),
    to_deliver_at: DateTime | nil,
    picked_up_at: DateTime | nil,
    pick_up_date: Date,
    delivery_date: Date
  }
}

delivery_picked_up

{
  event: 'delivery_picked_up',
  created_at: DateTime,
  resource_id: delivery_id,
  resource_type: 'delivery',
  ride_id: ride_id,
  data: {
    offer_id: offer_id,
    state: String (picked_up | to_deliver | completed | cancelled),
    to_deliver_at: DateTime | nil,
    picked_up_at: DateTime | nil,
    pick_up_date: Date,
    delivery_date: Date
  }
}

delivery_cancelled

{
  event: 'delivery_cancelled',
  created_at: DateTime,
  resource_id: delivery_id,
  resource_type: 'delivery',
  ride_id: ride_id,
  data: {
    offer_id: offer_id,
    state: String (picked_up | to_deliver | completed | cancelled),
    to_deliver_at: DateTime | nil,
    picked_up_at: DateTime | nil,
    pick_up_date: Date,
    delivery_date: Date
  }
}

delivery_completed

{
  event: 'delivery_completed',
  created_at: DateTime,
  resource_id: delivery_id,
  resource_type: 'delivery',
  ride_id: ride_id,
  data: {
    offer_id: offer_id,
    state: String (picked_up | to_deliver | completed | cancelled),
    to_deliver_at: DateTime | nil,
    picked_up_at: DateTime | nil,
    pick_up_date: Date,
    delivery_date: Date
  }
}

pickup_slot_accepted_by_sender

{
  event: 'pickup_slot_accepted_by_sender',
  created_at: DateTime,
  resource_id: ride_id,
  resource_type: 'ride',
  external_id: ride_external_id,
  external_description: Text,
  ride_id: ride_id
}

deposit_slot_accepted_by_recipient

{
  event: 'deposit_slot_accepted_by_recipient',
  created_at: DateTime,
  resource_id: ride_id,
  resource_type: 'ride',
  external_id: ride_external_id,
  external_description: Text,
  ride_id: ride_id
}