Skip to main content

signaloid-cli webhooks create

Create a new webhook.

Synopsis​

signaloid-cli webhooks create --url <url> --events <e1,e2,...> [options]

Options​

OptionRequiredDescription
--url <url>YesTarget https URL for webhook notifications. It must not point to a private or internal address.
--events <e1,e2,...>YesComma-separated event list: task-status, build-status, task-stats, build-stats, task-count, build-count. For details, see Webhook events.
--description <text>NoWebhook description
--status <active|disabled>NoInitial status
--payload-file <path>NoPath to a JSON file whose fields are merged into the create request (advanced). Field names are PascalCase, such as Description. The CLI rejects the old lowercase names, such as description.
--format <type>NoOutput format: table or json (default: json)

Description​

Creates a new webhook that will receive HTTP POST requests when subscribed events occur in your Signaloid account. The webhook will send event data as JSON payloads to the specified URL.

Examples​

The output of this command includes the webhook's signing Secret in plain text. This is the only time it is shown, because no other command returns it. Save it somewhere safe to verify deliveries, and do not store it in logs or share it.

signaloid-cli webhooks create \
--url https://api.example.com/webhooks/signaloid \
--events build-status,task-status \
--description "Production notifications"

Notes​

  • The target URL must be publicly accessible and support HTTPS
  • You must specify at least one event with --events. The CLI checks the event names, and the --status value, before it creates the webhook.
  • If --status is given and setting it fails after the webhook is created, the CLI still prints the created webhook, including its Secret, before it reports the error.
  • Webhooks are created in active status by default unless --status disabled is specified.
  • The webhook URL endpoint should return a 2xx status code to confirm successful delivery.

Troubleshooting​

Webhook creation fails with "Invalid URL"

  • Ensure the URL is properly formatted with the https:// protocol
  • Verify that the URL is publicly accessible

Events not being delivered

  • Check that the webhook status is active
  • Verify the target URL is responding correctly
  • Use webhooks stats to check delivery status

See Also​