Incoming webhooks are your gateway to seamless integration with external services and events. By creating a Webhook Receiver, you generate a unique URL that can be used as a webhook endpoint in other applications or platforms. Whenever that URL is called, CloudRay can automatically trigger actions like running a script.

How Webhook Receivers Work

  1. Create a Webhook Receiver: In CloudRay, navigate to the “Webhook Receivers” tab and click “New Webhook Receiver”.
  2. Configure the Receiver:
    • Name: Give your receiver a descriptive name (e.g., “GitHub Commit Receiver”, “Payment Notification”).
    • Action: Currently, the main action is “Run a Script.”
    • Script/Script Playlist: Select the script or script playlist you want to execute when the webhook is triggered.
    • Variable Group (Optional): If your script uses variables, choose the appropriate variable group.
  3. Save and Get URL: Click “Save Webhook Receiver.” This will generate a unique URL for your webhook.

Using the Webhook URL

  • External Integration: Copy the generated URL and paste it into the webhook configuration of your external service (e.g., GitHub, Stripe, Zapier).
  • Triggering Events: When an event occurs in the external service (e.g., a new commit, a payment), it will send an HTTP request to your CloudRay webhook URL.
  • CloudRay Action: CloudRay will receive the request, process any data included (query parameters or request body), and trigger the associated action (e.g., running your script).

Data Access in Scripts

When your script is triggered by a Webhook Receiver, you have access to the following data through built-in CloudRay variables:

  • {{ cr.webhook_query_params }}: This contains any query parameters included in the webhook URL.
  • {{ cr.webhook_post_body }}: This contains the body of the POST request (if any) sent by the external service.

You can use these variables within your script template to dynamically respond to the webhook data.

Important Considerations

  • Security: Be mindful of potential security risks when exposing a webhook endpoint to the internet. Consider using authentication mechanisms or IP whitelisting to restrict access to your webhook.
  • Data Validation: Always validate and sanitise any data received from the webhook before using it in your scripts to prevent vulnerabilities.
  • Debugging: Use Runlogs to inspect the data received from webhooks and troubleshoot any issues with your scripts or integrations.