Workflow webhooks allow Shapes to automatically notify your application when workflow events occur. When a workflow automation triggers, Shapes sends an HTTP POST request to your specified URL with relevant employee and workflow data.
Example use cases include creating a ticket in Jira to set up equipment or triggering an employee termination process in another platform — but the possibilities are endless. It’s important to note that the permissions applied to the fields sent with the webhook will be those of the user who last updated the task.
Creating a workflow
Follow the steps here to create a workflow template and run it on an employee.
In either the template or an assigned workflow, click "Add Task" and then "Send Webhook".
The task contains 3 components:
1. Due Date
2. Assignee
3. Content Details
Due Date
The webhook due date allows Shapes to understand when the action should go live. Only on the due date will the automation be triggered and the relevant data will be shared.
Assignee
In the case of the webhooks, Shapes is always the assignee.
Content Details
This contains the webhook URL, secret for security (optional), and chosen employee fields.
Webhook Data Flow
When the workflow triggers, Shapes sends a POST request to your URL with this payload:
{
"workflow": {
"id": "123",
"name": "Onboarding Workflow",
"workflowType": {
"id": "123",
"name": "Onboarding"
}
},
"workflowAutomation": {
"id": "123",
"name": "Open a ticket in Salesforce"
},
"employee": {
"id": "123",
"employeeFieldValues": [
{
"id": "123",
"textValue": "John",
"employeeFieldType": {
"id": "123",
"fieldName": "First Name",
"fieldType": "text",
"context": "first_name"
}
}
]
},
"timestamp": 1698765432100
}
Your server receives and processes the webhook data.
Securing Your Webhooks with a Secret
To ensure webhook requests genuinely come from Shapes, you can use a secret key. This is optional but strongly recommended for production.
How it Works: "Bring Your Own Secret"
You create a random secret string (treat it like a password)
You configure this secret in Shapes' webhook settings
Shapes signs each webhook request using your secret
Your server verifies the signature to confirm authenticity
When you configure a secret, Shapes includes these headers with each request:
X-Webhook-Signature: HMAC-SHA256 signature of the request body
X-Webhook-Timestamp: When the webhook was sent (Unix milliseconds)
Code Example: Verifying Webhook Signatures
Here's a complete example for a Node.js/Express server:
const crypto = require("crypto");
const express = require("express");
const app = express();
app.use(express.json());
// Store your secret securely (use environment variables)
const WEBHOOK_SECRET = process.env.SHAPES_WEBHOOK_SECRET;
function verifyWebhookSignature(requestBody, receivedSignature, secret) {
// Create signature from the request body
const expectedSignature = crypto.createHmac("sha256", secret).update(JSON.stringify(requestBody)).digest("hex");
// Securely compare signatures
return crypto.timingSafeEqual(Buffer.from(receivedSignature), Buffer.from(expectedSignature));
}
app.post("/shapes-webhook", (req, res) => {
// Verify signature if secret is configured
if (WEBHOOK_SECRET) {
const signature = req.headers["x-webhook-signature"];
if (!signature || !verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET)) {
console.log("Invalid webhook signature");
return res.status(401).json({ error: "Unauthorized" });
}
}
// Webhook is verified - process the data
const { workflow, employee, workflowAutomation } = req.body;
console.log(`Webhook received for employee ${employee.id}`);
console.log(`Workflow: ${workflow.name}`);
console.log(`Automation: ${workflowAutomation.name}`);
// Your business logic here
// processEmployeeData(employee);
// Always respond with 200 to acknowledge receipt
res.status(200).json({ received: true });
});
app.listen(3000, () => {
console.log("Webhook server running on port 3000");
});
If you have any questions, feel free to reach out to support@shapes.co