Webhooks

Webhooks let you receive HTTP POST notifications when events occur in ProBeya. Use them to integrate with external systems, trigger CI/CD pipelines, or build custom automation.

Setting Up a Webhook

Via the UI

1. Navigate to Settings > Integrations > Webhooks.
2. Click + Create Webhook.
3. Enter the endpoint URL (must be HTTPS).
4. Select the events you want to receive.
5. Optionally set a secret for payload verification.
6. Click Create.

Via the API

POST /trpc/webhook.create

{
  "url": "https://your-server.com/webhooks/probeya",
  "events": ["item.created", "item.updated", "item.deleted"],
  "secret": "your_webhook_secret"
}

Events

Event	Description
item.created	An item was created
item.updated	An item's fields were changed
item.deleted	An item was deleted
item.moved	An item was moved to a different group or board
board.created	A board was created
board.updated	A board was modified
board.deleted	A board was deleted
project.created	A project was created
project.deleted	A project was deleted
member.invited	A member was invited to the organization
member.joined	An invited member accepted and joined
member.removed	A member was removed from the organization
form.submitted	A form received a submission
comment.created	A comment was added to an item

Payload Format

All webhook payloads follow the same structure:

{
  "id": "evt_abc123",
  "event": "item.updated",
  "timestamp": "2026-03-18T14:30:00Z",
  "organizationId": "org_abc123",
  "data": {
    "item": {
      "id": "itm_abc123",
      "title": "Updated task",
      "boardId": "brd_xyz789",
      "groupId": "grp_abc123",
      "fields": {
        "status": "done"
      }
    },
    "changes": {
      "status": {
        "old": "in_progress",
        "new": "done"
      }
    },
    "actor": {
      "id": "usr_def456",
      "name": "Jane Doe",
      "email": "[email protected]"
    }
  }
}

Verifying Payloads

If you set a secret when creating the webhook, every request includes an X-ProBeya-Signature header containing an HMAC-SHA256 signature:

import { createHmac } from "crypto";

function verifyWebhook(
  payload: string,
  signature: string,
  secret: string,
): boolean {
  const expected = createHmac("sha256", secret).update(payload).digest("hex");
  return `sha256=${expected}` === signature;
}

Retry Policy

If your endpoint returns a non-2xx status code, ProBeya retries the delivery:

• 1st retry: After 1 minute.
• 2nd retry: After 5 minutes.
• 3rd retry: After 30 minutes.
• 4th retry: After 2 hours.
• 5th retry: After 12 hours.

After 5 failed attempts, the webhook is marked as failed. You can manually retry from the webhook settings or fix your endpoint and re-enable.

Webhook Logs

View delivery history for each webhook in Settings > Integrations > Webhooks > [webhook name] > Logs. Each log entry shows:

• Event type and timestamp.
• HTTP status code returned by your endpoint.
• Request and response bodies.
• Delivery duration.