Overview
Webhooks allow external services to receive real-time notifications when events occur in Obeya Cloud. When an event is triggered, Obeya Cloud sends an HTTP POST request to your configured endpoint with a JSON payload describing the event.
Setting Up Webhooks
Navigate to Webhooks
Go to Settings > Integrations > Webhooks or Project Settings > Webhooks for project-level hooks.
Add Endpoint
Click + Add Webhook and enter your endpoint URL (must be HTTPS in production).
Select Events
Choose which events trigger the webhook. You can select individual events or subscribe to all events.
Set Secret
Generate or enter a signing secret. Obeya Cloud uses this to sign payloads so you can verify authenticity.
Test
Click Send Test to send a test payload to your endpoint and verify it is working.
Available Events
| Event | Trigger |
|---|
item.created | A new item is created |
item.updated | An item’s name or description changes |
item.deleted | An item is permanently deleted |
item.archived | An item is archived |
item.moved | An item is moved to a different group or board |
value.changed | A column value is set or updated |
column.created | A new column is added to a board |
column.deleted | A column is removed from a board |
comment.created | A new comment is posted |
board.created | A new board is created |
board.deleted | A board is deleted |
member.invited | A new member is invited to the organization |
member.removed | A member is removed from the organization |
form.submitted | A form receives a submission |
{
"id": "evt_01HXK5QJBN3YZXM8KJP2RSNV4C",
"type": "item.created",
"timestamp": "2026-03-19T14:30:00.000Z",
"organization": {
"id": "org_01HXK5...",
"slug": "acme"
},
"data": {
"item": {
"id": "itm_01HXK5...",
"name": "New feature request",
"boardId": "brd_01HXK5...",
"groupId": "grp_01HXK5...",
"createdBy": "usr_01HXK5...",
"createdAt": "2026-03-19T14:30:00.000Z",
"values": {
"status": { "label": "To Do", "color": "#6366f1" },
"priority": { "label": "High", "color": "#ef4444" },
"assignee": ["usr_01HXK5..."]
}
}
}
}
Signature Verification
Every webhook request includes a signature header for verification:
X-Obeya-Signature: sha256=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
import crypto from "crypto";
function verifyWebhook(payload, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(payload)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(`sha256=${expected}`),
Buffer.from(signature)
);
}
// Express middleware
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
const signature = req.headers["x-obeya-signature"];
if (!verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).send("Invalid signature");
}
const event = JSON.parse(req.body);
console.log("Received event:", event.type);
res.status(200).send("OK");
});
import hmac
import hashlib
def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(
secret.encode(),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(f"sha256={expected}", signature)
# Flask example
@app.route("/webhook", methods=["POST"])
def handle_webhook():
signature = request.headers.get("X-Obeya-Signature")
if not verify_webhook(request.data, signature, WEBHOOK_SECRET):
return "Invalid signature", 401
event = request.json
print(f"Received event: {event['type']}")
return "OK", 200
Retry Policy
If your endpoint returns a non-2xx status code or times out (30 second timeout), Obeya Cloud retries the delivery:
| Attempt | Delay |
|---|
| 1st retry | 1 minute |
| 2nd retry | 5 minutes |
| 3rd retry | 30 minutes |
| 4th retry | 2 hours |
| 5th retry | 12 hours |
If a webhook endpoint consistently fails (5+ consecutive failures), it is automatically disabled. You will receive an email notification and can re-enable it after fixing the issue.
Webhook Logs
View delivery logs for each webhook in Settings > Webhooks > [Webhook Name] > Logs. Each log entry shows:
- Event type and payload
- Response status code and body
- Delivery time
- Retry attempts
Webhook logs are retained for 30 days. Export them from the dashboard if you need longer-term storage.
