Skip to main content
Creating webhooks

Creating Webhooks: A Step-by-Step Guide

Gabriele Gallo Stampino avatar
Written by Gabriele Gallo Stampino
Updated this week

In today's fast-paced development environments, real-time communication between systems is essential for seamless integration and automation. Webhooks are a powerful mechanism to achieve this, enabling Clayton to notify your application whenever a specific event occurs.

Creating Webhooks: A Step-by-Step Guide

Webhooks allow Clayton to send real-time updates to your application. Follow these steps to create and configure a webhook for your project.

Step 1: Navigate to the Webhooks Page

To access webhooks settings, go to your project (Repository or Environment), click Settings, and select Webhooks.

Step 2: Add a New Webhook

  1. Click Add Webhook.

  2. Configure an Endpoint URL where webhook payloads will be sent.

  3. (Optional) Configure a Secret to secure the webhook payloads.

  4. (Optional) Activate the webhook to broadcast events immediately.

  5. Click Add Webhook to save the configuration.

Customize your webhook payload

Default settings offer a convenient starting point, allowing users to quickly integrate Clayton into their workflows. However, as your integration needs evolve, creating tailored payloads for Webhook endpoints becomes critical. Custom Payloads provide the flexibility to address specific requirements, making them especially valuable for integrating Clayton with diverse systems and tools.

Customizing a Webhook payload allows you to include only the data that is most relevant to your workflows. This approach supports complex integrations by adapting payload structures to meet the precise requirements of third-party systems or in-house tools. By designing payloads that align with your automation processes, you can streamline workflows and minimize the need for manual interventions.


Configuring a custom payload involves defining the Webhook in Clayton's settings, specifying an endpoint URL, and optionally including a secret for secure communication. Template variables such as $event for the type of triggered event, $workspaceName for identifying the source workspace, or $reportHtmlUrl for linking detailed reports, help structure payloads with dynamic and meaningful content. This ensures that the data transmitted is both accurate and actionable.

You can configure two types of templates:

  • Sample

{
"event": "$event",
"data": {
"report_result": "$reportResult",
"report_url": "$reportHtmlUrl"
}
}
  • Copado DevOps Actions: RunJobTemplate

{
"payload": {
"templateName": "My_Job_Template",
"runAfterInstantiation" : true,
"dataJson" : "$claytonEventPayloadStringified",
"preSteps" : [],
"postSteps" : [],
"additionalSteps" : []
}
}

Template Variables

You can use Template Variables to customize your notification payloads. Commonly, these are used to pass dynamic values from an Attribute into the placeholders of a Template. A Template Variable can be referenced in any Template using the syntax $variableName.

Variable

Description

Value

claytonEventPayloadStringified

A variable that represents the entire Clayton event payload.

event

The event that generated the webhook.

PING, SCAN_READY, PR_READY, DIFF_READY

workspaceId

The Clayton Identifier of the workspace.

f123dd7f-9766-4i83-8760-9a0a28w51vb9

workspaceName

The Clayton workspace Name.

Acme Inc.

projectId

The Clayton Identifier of the project.

1f713e2d-bf75-4693-ab54-04aa159a7142

projectName

The Clayton project Name.

DevSecOps Repo

reportId

The Clayton Identifier of the scan report.

527b185d-d81d-41c2-9s7e-2c862ye063b4

reportResult

The result of the scan.

PASSED, PASSED_WITH_WARNINGS, NOT_PASSED

reportHtmlUrl

The Clayton report URL.

reportHtmlPullRequestId

The Clayton Identifier of the Pull Request. Available only for PR_READY and DIFF_READY events.

da40635c-8a5f-4775-bfd9-8bf34864d18e

reportHtmlPullRequestNumber

The external identifier of the Pull Request. Available only for PR_READY events.

12



Did this answer your question?