Webhooks

The sulu.ai platform pushes changes to your installation in real time via a webhook — built on Symfony's webhook component. Today this keeps your experts and their variants up to date automatically whenever their configuration changes on the platform; more platform events will be delivered over this channel in future releases.

Registration

Register the webhook endpoint once per environment:

php bin/console sulu:ai:register-webhook

The command registers your installation's endpoint on the platform and prints the shared secret.

Important: The secret is displayed only once. Store it in your environment variables immediately:

SULU_AI_WEBHOOK_SECRET=<webhook-secret>

The secret is wired into the bundle configuration (see Configuration → webhook):

sulu_ai_platform:
    webhook:
        secret: '%env(SULU_AI_WEBHOOK_SECRET)%'

All active webhooks are listed in your project settings on the sulu.ai platform.

How it works

• Incoming requests are routed through Symfony's webhook component under the sulu_ai routing key and parsed by the bundle's request parser.
• Every request is authenticated with the shared secret — requests without a valid secret are rejected.
• Received events update the locally stored experts automatically, replacing the need for routine manual synchronization.

Lost Secret

Running the register command again while the webhook still exists fails with "Webhook endpoint already registered!". To obtain a new secret:

1. Delete the existing webhook in your project settings on the sulu.ai platform.

2. Register again:

   php bin/console sulu:ai:register-webhook
   

3. Replace the SULU_AI_WEBHOOK_SECRET environment variable with the newly printed value.

Environments Without a Public Endpoint

Local development machines or CI environments usually cannot receive webhooks. That is fine — fall back to manual synchronization when needed:

php bin/console sulu:ai:synchronize-experts