Circuit Webhooks
Circuit Incoming Webhooks enable you to easily post content to a given Circuit conversation.
A webhook is a specific unique URL generated by Circuit for a given user (or bot user) to post to a given conversation.
In effect, the URL encapsulates the ID of the conversation, the ID of the user posting and the ID of the webhook itself. Posting to this URL does not require authentication. As a result, the URL is meant to keep secret. If it was to shared or revealed, other users could publish on behalf of the webhook owner. In case the URL may have been comprimised, it can be re-generated.
This design is one of the strength of webhooks as they enable simple (friction less) integrations between applications
Pre-requisites
Incoming Webhooks are available to all users if the Circuit tenant admin enabled the feature for the tenant in the Circuit administration console.
Creating a webhook
- Open the sidebar and click on add an app or the + button
- Name your incoming webhook and click on Create
- >You will get the incoming webhook URL, copy it to clipboard
- You can post to Circuit using this URL
curl --insecure -X POST https://yourcircuit.com/rest/v2/webhooks/incoming/1234392e25a0c-c88f-4eab-a27e-f88ccd657d17 -d '{"text": "This is the content of my post"}'
Formatting
Circuit supports bold, italic and highlited texts. It supports line breaks and ordered and lists with bullet points and numbered items. See the code below for examples :
Example
circuit-call-me-button
In this example, a page presents a form where users can enter their name and contact details. Upon submitting, a message is posted to a Circuit conversation so that Circuit participants can see incoming requests and get back to end users.
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Circuit - Incoming Webhooks</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/skeleton/2.0.4/skeleton.min.css">
<style>
body {
background: #f7f7f7;
}
.form-box {
max-width: 500px;
margin: auto;
padding: 50px;
background: #ffffff;
border: 10px solid #f2f2f2;
}
.logo {
text-align: center;
max-width: 40%;
display: block;
margin: 0 auto 20px auto;
}
h1, p {
text-align: center;
}
input, textarea {
width: 100%;
}
input[type=submit] {
background-color: #82bd3f !important;
border: solid 1px #82bd3f !important;
}
</style>
</head>
<body>
<div class="form-box">
<img src="https://d3bql97l1ytoxn.cloudfront.net/app_resources/194960/myAppIcon/img6311084438843840511-2x.png" alt="Circuit Logo" class="logo">
<h1>Let Us Call You Back</h1>
<p>
We'd hate to make you wait.<br>
Leave us your name and phone number and we will call you right back.
</p>
<form id="callbackForm" action="" method="post">
<label for="name">Name</label>
<input id="name" type="text" name="Name">
<label for="phone">Phone</label>
<input id="phone" type="tel" name="Phone">
<label for="message">Message</label>
<textarea id="message" name="Message"></textarea>
<input class="button-primary" type="submit" value="Submit" />
</form>
</div>
<script>
var webhookUrl = 'https://beta.circuit.com/rest/v2/webhooks/incoming/d6b78c30-3f6c-4f2e-b0f5-a704e7f5e7c7';
document.querySelector("#callbackForm").addEventListener("submit", function(e) {
e.preventDefault();
var xhr = new XMLHttpRequest();
xhr.open("POST", webhookUrl, true);
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.send(JSON.stringify({
text: "New callback request <br>Name : " + document.getElementById('name').value + "<br>Phone Number : " + document.getElementById('phone').value + " <br>Message : " + document.getElementById('message').value
}));
});
</script>
</body>
</html>