Overview

Webhooks allow you to receive real-time notifications when workflow events occur. Configure a webhook URL, and yWorkflow will send HTTP POST requests to your endpoint whenever events happen.

Configuring Webhooks

1

Navigate to Webhook Tab

Open the main dashboard and select the "Webhook" tab from the navigation.

2

Enter Webhook URL

Provide a valid HTTPS URL for your webhook endpoint. The URL must:

  • Be a valid domain (IP addresses are not allowed)
  • Use HTTPS in production (HTTP allowed in dev mode)
  • Be accessible from the internet
3

Add Custom Headers (Optional)

You can add up to 3 custom headers (key-value pairs) that will be included in all webhook requests. This is useful for authentication or custom metadata.

4

Enable Webhooks

Toggle the "Enabled" switch to activate webhooks. The save button is only enabled when changes are detected.

5

Save Configuration

Click "Save" to store your webhook configuration. Success or error messages will be displayed.

Webhook Secret

Each webhook configuration has a shared secret that you can use to verify the authenticity of webhook requests. This helps ensure that requests are actually coming from yWorkflow.

Viewing the Secret

The webhook secret is hidden by default for security. Click the "Show" button to reveal it, or "Copy" to copy it to your clipboard.

Rotating the Secret

You can rotate the webhook secret at any time. This generates a new secret and invalidates the old one. Use this for security best practices:

  • Generate a new secret periodically
  • Rotate immediately if you suspect the secret has been compromised
  • Update your webhook endpoint to use the new secret for verification

💡 Tip: Use the webhook secret to verify the signature of incoming webhook requests. This ensures the requests are authentic and haven't been tampered with.

URL Validation

The application validates webhook URLs to ensure they meet security requirements:

  • Protocol: Must be HTTPS
  • Domain Format: Must be a valid domain name (not an IP address)
  • Accessibility: The URL must be accessible from the internet

⚠️ Security Note: IP addresses are not allowed to prevent potential security issues. Always use proper domain names.

Organization Scoping

Webhook configurations are organization-scoped. This means:

  • Each organization has its own webhook configuration
  • When you switch organizations, you'll see different webhook settings
  • Webhook events are scoped to the organization that triggered them

Note: If you belong to multiple organizations, you can configure different webhooks for each one. This allows you to route events to different endpoints based on the organization.

Best Practices

🔐 Verify Webhook Signatures

Always verify webhook signatures using the shared secret to ensure requests are authentic.

⚡ Handle Requests Quickly

Respond to webhook requests quickly (within a few seconds) to avoid timeouts. Process events asynchronously if needed.

🔄 Implement Idempotency

Design your webhook handler to be idempotent. The same event may be delivered multiple times.

📝 Log Webhook Events

Log all incoming webhook events for debugging and audit purposes.

🔄 Rotate Secrets Regularly

Rotate webhook secrets periodically as part of your security practices.

Previous: Workflow Executions Next: Organization Management