Les webhooks permettent à PixShrink de notifier ton serveur en temps réel quand un événement survient (conversion terminée, clé créée, etc.). Au lieu d'interroger l'API en boucle, ton endpoint reçoit un appel HTTP automatique.

Prérequis

Être connecté à un compte Pro Plus. Disposer d'un serveur avec un endpoint HTTPS public capable de recevoir des requêtes POST et de répondre en moins de 10 secondes.

Créer un endpoint webhook

Rends-toi sur /compte/api/.
Fais défiler jusqu'à la section Notifications webhook.
Remplis le formulaire :

Champ	Obligatoire	Description	Erreur fréquente
URL du endpoint	Oui	URL HTTPS publique de ton serveur (max 2048 caractères). HTTP est accepté mais HTTPS fortement recommandé.	URL et au moins un event requis.
Events (cases à cocher)	Au moins un	`job.created`, `job.completed` (coché par défaut), `job.failed` (coché par défaut), `api_key.created`, `api_key.revoked`	Events inconnus : [liste]. Supportés : [liste].
Description	Non	Note interne pour identifier cet endpoint (max 200 caractères)	—

Clique sur Enregistrer le webhook.
La page affiche un encart Ton webhook secret avec la valeur en clair.

Le secret webhook n'est affiché qu'une seule fois. Copie-le immédiatement et stocke-le côté serveur (variable d'environnement). Il ne sera plus accessible ensuite. Ne le place jamais dans du code client ou dans un dépôt public.

Vérifier la signature des payloads reçus

Chaque requête webhook envoyée par PixShrink inclut les headers suivants :

Header	Description
`X-PixShrink-Signature`	HMAC-SHA256 du body JSON, au format `sha256=<hex>`
`X-PixShrink-Event`	Nom de l'événement (ex: `job.completed`)
`X-PixShrink-Delivery`	UUID unique de cette livraison (utile pour les logs)

Pour vérifier la signature en Python :

import hmac
import hashlib

def verify_signature(body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Si la vérification échoue, rejette la requête — elle ne provient pas de PixShrink ou a été altérée en transit.

Structure d'un payload webhook

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "job.completed",
  "created_at": "2026-06-11T14:00:00+00:00",
  "data": { ... }
}

Le champ data contient l'objet complet correspondant à l'événement (objet job pour job.*, objet clé pour api_key.*).

Répondre correctement à un webhook

Ton endpoint doit :

Répondre avec un code HTTP 2xx (200, 201, 204…) pour indiquer que le message a bien été reçu.
Répondre dans les 10 secondes maximum.
Si le traitement est long, répondre 200 immédiatement et traiter en arrière-plan.

Politique de retry en cas d'échec

Si ton endpoint répond avec un code non-2xx ou dépasse le timeout de 10 secondes, PixShrink retente la livraison selon le calendrier suivant :

Tentative	Délai après l'essai précédent
1re (initiale)	Immédiat
2e	+1 seconde
3e	+10 secondes
4e	+60 secondes

Après 3 échecs consécutifs, la livraison passe au statut failed_permanent et n'est plus retentée. L'historique des livraisons est consultable dans le back-office.

Supprimer un endpoint webhook

Sur /compte/api/, repère le tableau des endpoints actifs.
Clique sur Supprimer en regard de l'endpoint.
Confirme la suppression dans le dialogue qui s'affiche.

L'endpoint est supprimé immédiatement. Les livraisons en cours ou en attente de retry sont abandonnées. Un message flash confirme : Endpoint supprimé.

Gérer les webhooks via l'API REST

Tu peux aussi créer et supprimer des endpoints programmatiquement :

# Créer un endpoint
POST /api/v1/webhooks
Authorization: Bearer px_live_...
Content-Type: application/json

{
  "url": "https://ton-serveur.com/webhook",
  "events": ["job.completed", "job.failed"]
}

# Supprimer un endpoint
DELETE /api/v1/webhooks/{id}
Authorization: Bearer px_live_...

Attention : via l'API REST, le secret est renvoyé dans la réponse JSON — à stocker immédiatement. Consulte /api/v1/docs pour le détail.

Questions fréquentes

Mon endpoint ne reçoit rien, comment déboguer ?

Vérifie d'abord que l'URL est publiquement accessible (pas localhost, pas derrière un VPN). Assure-toi que ton serveur répond bien en HTTPS. Si l'URL est correcte mais les livraisons échouent, consulte l'historique des livraisons dans le back-office PixShrink ou contacte le support.

Puis-je m'abonner à tous les événements d'un coup ?

Oui — via l'API REST, tu peux utiliser "events": ["*"] pour t'abonner à tous les événements. Via le formulaire HTML, coche toutes les cases.

J'ai perdu mon secret webhook, que faire ?

Il n'est pas récupérable. Supprime l'endpoint existant et crée-en un nouveau — un nouveau secret sera généré et affiché une seule fois.

Voir aussi : Convertir des images via l'API · Créer une clé API