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
Click Add Webhook.
Configure an Endpoint URL where webhook payloads will be sent.
(Optional) Configure a Secret to secure the webhook payloads.
(Optional) Activate the webhook to broadcast events immediately.
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 |