Ces appels utilisent la clé de votre entreprise plateforme, pas la clé plateforme. L'abonnement est créé sur le magasin dédié : la liste et la suppression ne portent que sur vos abonnements, pas sur ceux des autres Plateformes du marchand, ni sur les webhooks magasin du marchand lui-même.
La signature et les reprises sont dans Webhooks. Chaque Kelyko-Event et son corps sont dans Événements.
Si Kelyko suspend le plateforme, les événements du magasin dédié ne sont plus envoyés. L'abonnement reste. La réactivation reprend les envois sur la même URL, sans le recréer. Voir Suspension.
Créer l'abonnement
Un marchand n'a qu'un abonnement actif sur votre magasin dédié.
POST /partner_api/service_providers/business_webhook_subscriptions
Requête :
{
"merchantBusinessId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
"url": "https://partner.example/webhooks/Kelyko",
"name": "Production",
"events": ["TRANSACTION_COMPLETED", "SERVICE_PROVIDER_LINK_REQUEST"]
}
merchantBusinessId et url sont obligatoires. url doit être en https. name est optionnel (255 caractères au plus). events est optionnel.
Réponse (201) :
{
"id": "b7e2c1a0-4d5f-4a6b-8c9d-0e1f2a3b4c5d",
"url": "https://partner.example/webhooks/Kelyko",
"name": "Production",
"businessId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
"events": ["TRANSACTION_COMPLETED", "SERVICE_PROVIDER_LINK_REQUEST"],
"createdAt": "2026-09-25T12:00:00.000Z",
"updatedAt": "2026-09-25T12:00:00.000Z",
"secret": "whsec_returned_only_once"
}
Point d’attention.
secret n'est renvoyé qu'à la création. C'est la clé HMAC de l'en-tête Kelyko-Signature. Stockez-la tout de suite.
Si events est omis, la valeur enregistrée est null. Cet abonnement est rattaché à votre magasin dédié : il reçoit chaque événement que Kelyko route vers ce magasin, y compris SERVICE_PROVIDER_LINK_REQUEST, ESCROW_HELD, ESCROW_RELEASED, ESCROW_REFUNDED et COMPLIANCE_VERIFICATION_COMPLETED. Un tableau qui ne contient que TRANSACTION_COMPLETED laisse tomber les autres. Les valeurs et les corps sont dans Événements.
HMAC-SHA256 porte sur le corps JSON brut. Branchez le traitement sur l'en-tête Kelyko-Event.
id d'erreur |
HTTP | Signification |
|---|---|---|
max_webhook_subscriptions_reached |
409 | Un abonnement actif existe déjà sur votre magasin dédié chez ce marchand |
| — | 401 | Marchand non rattaché à votre plateforme |
| — | 422 | url absente, non https, ou valeur d'events inconnue |
Lister
GET /partner_api/service_providers/business_webhook_subscriptions?merchantBusinessId={merchantBusinessId}
Réponse (200) : tableau d'abonnements. Le secret n'y figure pas.
[
{
"id": "b7e2c1a0-4d5f-4a6b-8c9d-0e1f2a3b4c5d",
"url": "https://partner.example/webhooks/Kelyko",
"name": "Production",
"businessId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
"events": null,
"createdAt": "2026-09-25T12:00:00.000Z",
"updatedAt": "2026-09-25T12:00:00.000Z"
}
]
Supprimer
DELETE /partner_api/service_providers/business_webhook_subscriptions/{subscriptionId}?merchantBusinessId={merchantBusinessId}
Réponse (200) : un objet dont message est optionnel. Un abonnement introuvable renvoie 404, avec le même objet.
Le détachement ne supprime pas les webhooks du marchand.