> ## Documentation Index
> Fetch the complete documentation index at: https://docs.so-me.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Créez, gérez et inspectez des abonnements webhook depuis la CLI

Les webhooks envoient en temps réel les événements de Social media studio vers votre serveur. Utilisez ces commandes pour gérer les abonnements, envoyer des livraisons de test, consulter les journaux de livraison et relancer les tentatives en échec sans quitter votre terminal.

> [!NOTE]
>
> Les limites des webhooks selon l'offre (abonnements max., conservation des journaux) sont appliquées côté serveur. Consultez la [présentation des webhooks](/fr/webhooks/overview.md) pour la matrice complète des limites et la référence des modèles de charge utile.

> [!NOTE]
>
> Chaque commande ci-dessous respecte les options globales : `--json` (par défaut) ou `--table` pour le format de sortie, `--verbose` pour des journaux supplémentaires, et `--api-key <key>` / `--api-url <url>` pour remplacer les identifiants (configurables aussi via les variables d'environnement `SOME_API_KEY` et `SOME_API_URL`).

## webhooks:create

Crée un nouvel abonnement webhook.

```bash theme={null}
so-me webhooks:create --url <url> --categories <csv> [options]
```

| Option | Description |
| - | - |
| `--url <url>` | Endpoint HTTPS recevant les livraisons **(obligatoire)** |
| `--categories <csv>` | Catégories séparées par des virgules : `post`, `draft`, `approval`, `social`, `media`, `composer`, `analytics`, `inbox`, `biolink`, `ai`, `team`, `organization`, `account`, `auth`, `api_key`, `webhook`, `integration`, `subscription`, `support`, `template`, `referral`, `mcp`, `quota` **(obligatoire)** |
| `--events <csv>` | Noms d'événements séparés par des virgules pour un contrôle plus fin (sous-ensemble des catégories) |
| `--description <text>` | Libellé lisible |
| `--payload-template <json>` | Modèle de corps JSON personnalisé avec les variables `{{event}}`, `{{category}}`, `{{timestamp}}`, `{{data}}` |

```bash Exemples theme={null}
# Minimal — subscribe to all post events
so-me webhooks:create \
  --url https://example.com/hooks/some \
  --categories post

# Subscribe to multiple categories
so-me webhooks:create \
  --url https://example.com/hooks/some \
  --categories post,inbox,approval \
  --description "Production endpoint"

# Subscribe to specific events only (narrower than categories)
so-me webhooks:create \
  --url https://example.com/hooks/some \
  --categories post \
  --events post.published,post.failed

# Discord-friendly payload template
so-me webhooks:create \
  --url https://discord.com/api/webhooks/xxx/yyy \
  --categories post,approval \
  --payload-template '{"content":"🚀 {{event}} at {{timestamp}}"}'

# Slack-friendly payload template from a file
so-me webhooks:create \
  --url https://hooks.slack.com/services/xxx \
  --categories inbox \
  --payload-template "$(cat ./slack-template.json)"
```

> [!TIP]
>
> La réponse inclut une valeur `secret` à usage unique. Conservez-la — elle sert à vérifier les en-têtes `X-Webhook-Signature` des livraisons entrantes et n'est renvoyée qu'à la création.

## webhooks:list

Liste tous les abonnements webhook de l'espace de travail actuel.

```bash theme={null}
so-me webhooks:list
```

```bash Exemples theme={null}
# Default JSON output
so-me webhooks:list

# Formatted table
so-me webhooks:list --table

# Pipe to jq — only active endpoints
so-me webhooks:list | jq '.[] | select(.isActive == true) | {id, url, categories}'

# Count subscriptions
so-me webhooks:list | jq 'length'
```

## webhooks:get

Récupère un abonnement par son ID, avec son état actuel et ses compteurs d'échecs.

```bash theme={null}
so-me webhooks:get <id>
```

```bash Exemples theme={null}
# Full details as JSON
so-me webhooks:get 550e8400-e29b-41d4-a716-446655440000

# Check just the URL and status
so-me webhooks:get 550e8400-... | jq '{url, isActive, consecutiveFailures}'
```

## webhooks:update

Met à jour n'importe quel champ d'un abonnement existant. Seuls les champs que vous indiquez sont modifiés.

```bash theme={null}
so-me webhooks:update <id> [options]
```

| Option | Description |
| - | - |
| `--url <url>` | Modifie l'URL de l'endpoint |
| `--categories <csv>` | Remplace les catégories auxquelles l'abonnement est souscrit |
| `--events <csv>` | Remplace les événements auxquels l'abonnement est souscrit |
| `--description <text>` | Met à jour le libellé |
| `--payload-template <json>` | Remplace le modèle de charge utile |
| `--active` | Active l'abonnement (définit `isActive: true`) |
| `--inactive` | Désactive l'abonnement (définit `isActive: false`, arrête les livraisons) |
| `--regenerate-secret` | Renouvelle le secret de signature (invalide l'ancien) |

> [!NOTE]
>
> Au moins un champ doit être fourni, sinon la commande se termine avec une erreur. `--active` et `--inactive` s'excluent mutuellement — les passer ensemble provoque également une erreur.

```bash Exemples theme={null}
# Change endpoint URL
so-me webhooks:update 550e8400-... \
  --url https://new.example.com/hooks/some

# Swap category subscriptions
so-me webhooks:update 550e8400-... \
  --categories post,inbox,media

# Narrow down to specific events
so-me webhooks:update 550e8400-... \
  --events post.published,post.failed,inbox.message_received

# Temporarily disable an endpoint
so-me webhooks:update 550e8400-... --inactive

# Re-enable it later
so-me webhooks:update 550e8400-... --active

# Rotate the signing secret (old signatures become invalid)
so-me webhooks:update 550e8400-... --regenerate-secret

# Update label and payload template together
so-me webhooks:update 550e8400-... \
  --description "Staging endpoint" \
  --payload-template '{"event":"{{event}}","data":{{data}}}'

# Combine multiple updates in one call
so-me webhooks:update 550e8400-... \
  --url https://new.example.com/hooks/some \
  --categories post,approval \
  --active
```

> [!WARNING]
>
> `--regenerate-secret` invalide immédiatement l'ancien secret. Le nouveau secret est renvoyé dans la réponse de mise à jour — adaptez votre code de vérification pour l'utiliser avant de procéder à la rotation en production.

## webhooks:delete

Supprime définitivement un abonnement. Plus aucune livraison n'est tentée.

```bash theme={null}
so-me webhooks:delete <id>
```

```bash Exemples theme={null}
# Remove a subscription
so-me webhooks:delete 550e8400-e29b-41d4-a716-446655440000

# Remove every inactive subscription in one pipeline
so-me webhooks:list \
  | jq -r '.[] | select(.isActive == false) | .id' \
  | xargs -I {} so-me webhooks:delete {}
```

## webhooks:test

Met en file d'attente une livraison synthétique `webhook.test` pour vérifier que votre endpoint est joignable et que votre vérification de signature fonctionne.

```bash theme={null}
so-me webhooks:test <id>
```

```bash Exemples theme={null}
# Fire a test against a known subscription
so-me webhooks:test 550e8400-e29b-41d4-a716-446655440000

# Test every active subscription at once
so-me webhooks:list \
  | jq -r '.[] | select(.isActive == true) | .id' \
  | xargs -I {} so-me webhooks:test {}
```

> [!TIP]
>
> La charge utile de test utilise toujours le nom d'événement `webhook.test` et la catégorie `test`, quelles que soient les catégories configurées pour l'abonnement. Votre endpoint peut ainsi traiter rapidement le trafic synthétique.

## webhooks:deliveries

Liste les tentatives de livraison récentes (réussies et en échec) avec pagination.

```bash theme={null}
so-me webhooks:deliveries [options]
```

| Option | Description |
| - | - |
| `--page <number>` | Numéro de page (par défaut : 1) |
| `--limit <number>` | Éléments par page (par défaut : 20) |

```bash Exemples theme={null}
# Recent 20 deliveries
so-me webhooks:deliveries

# Next page
so-me webhooks:deliveries --page 2

# Larger page as a table
so-me webhooks:deliveries --limit 100 --table

# Only the failed ones
so-me webhooks:deliveries --limit 100 \
  | jq '.data[] | select(.status != "success")'

# Count failures in the most recent page
so-me webhooks:deliveries --limit 100 \
  | jq '[.data[] | select(.status != "success")] | length'
```

## webhooks:retry

Remet en file d'attente une livraison précédemment en échec. Utilise l'abonnement, l'événement et la charge utile d'origine.

```bash theme={null}
so-me webhooks:retry <delivery-id>
```

```bash Exemples theme={null}
# Retry a single delivery by its log ID
so-me webhooks:retry 7c2d4e8f-1a2b-3c4d-5e6f-7890abcdef12

# Retry every failed delivery from the last page
so-me webhooks:deliveries --limit 100 \
  | jq -r '.data[] | select(.status == "failed") | .id' \
  | xargs -I {} so-me webhooks:retry {}
```

> [!WARNING]
>
> Relancer une livraison dont l'abonnement a été supprimé renvoie une erreur. Vérifiez d'abord avec `webhooks:get` en cas de doute.

## webhooks:events

Liste tous les noms d'événements pris en charge par l'API, regroupés par catégorie. Utile pour construire des filtres `--events` ou valider la configuration de votre abonnement. La réponse est un tableau d'objets `{ category, label, events }`.

```bash theme={null}
so-me webhooks:events
```

```bash Exemples theme={null}
# Full catalog as JSON
so-me webhooks:events

# As a table
so-me webhooks:events --table

# Only the inbox events
so-me webhooks:events | jq '.[] | select(.category == "inbox") | .events'

# Flat list of all event names
so-me webhooks:events | jq -r '.[].events[]'

# Count events per category
so-me webhooks:events | jq 'map({category, count: (.events | length)})'
```

> **[Charges utiles et vérification de signature](/fr/webhooks/payloads.md)**
>
> Consultez des exemples de charges utiles pour chaque catégorie d'événements et découvrez comment vérifier l'en-tête `X-Webhook-Signature`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.