Webhooks

Webhooks push a signed HTTP request to your server whenever something changes in your workspace — new time entries, approvals, billing packets and more. Events are written in the same database transaction as the change itself, so a delivery may be retried, but it is never lost.

Creating an endpoint

Only workspace owners can manage webhooks. In the app, open Webhooks in the sidebar and add an endpoint with the URL that should receive deliveries, an optional description, and the events you care about.

Events are grouped by app, then entity. Leaving all event checkboxes unticked subscribes the endpoint to every event — including types added in the future.

Each endpoint gets its own signing secret, shown once at creation. You can rotate it at any time; from that moment deliveries are signed with the new secret.

Use the Test button to send a ping event, and the delivery log on each endpoint to inspect attempts, response codes and errors.

The delivery request

Deliveries are HTTP POST requests with a JSON body. The envelope is the same for every event; data carries the affected entity (deletions may carry only its id):

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "time_entry.created",
  "createdAt": "2026-08-17T09:30:00.000Z",
  "organizationId": "…",
  "data": { "id": "…" }
}

Every delivery carries these headers:

Verifying signatures

The X-Shrimp-Signature header is an HMAC-SHA256 of the raw request body, keyed with the endpoint's secret, hex-encoded and prefixed with sha256=. Verify it against the raw bytes before parsing the JSON, and reject anything that does not match:

import { createHmac, timingSafeEqual } from "node:crypto";

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = `sha256=${createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex")}`;
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Use a constant-time comparison as in the example — a plain string comparison leaks timing information.

Responding and retries

Answer with any 2xx status within 10 seconds — anything else, including a timeout, counts as a failed attempt. Acknowledge first, process after.

Failed deliveries are retried up to 6 times with growing pauses; after the sixth failure — roughly 8.5 hours after the event — the delivery is marked failed for good:

1m · 5m · 30m · 2h · 6h · 12h

Endpoints are never disabled automatically. Failed deliveries show up in the delivery log; fix the receiver and future events flow again.

New events usually arrive within a few seconds of the change.

Event types

These are all event types an endpoint can subscribe to. The ping event sent by the Test button is special: it is always delivered, regardless of the subscription.

• customer.created
• customer.updated
• customer.deleted
• project.created
• project.updated
• project.deleted
• project.member_assigned
• project.member_unassigned
• task.created
• task.updated
• task.deleted
• time_entry.created
• time_entry.updated
• time_entry.deleted
• time_entry.approved
• time_entry.rejected
• timer.started
• timer.stopped
• day_off.created
• day_off.deleted
• day_off.approved
• day_off.rejected
• member.role_updated
• member.requires_approval_updated
• member.removed
• organization.updated
• billable_packet.created
• billable_packet.sent
• billable_packet.deleted
• employee.created
• employee.updated
• employee.deleted
• contract.created
• contract.updated
• contract.deleted
• vacation_adjustment.created
• vacation_adjustment.deleted
• crm_company.created
• crm_company.updated
• crm_company.archived
• crm_company.restored
• crm_company.customer_linked
• crm_contact.created
• crm_contact.updated
• crm_contact.archived
• crm_contact.restored
• crm_deal.created
• crm_deal.updated
• crm_deal.archived
• crm_deal.restored
• crm_deal.stage_changed
• crm_activity.created
• crm_follow_up.completed

CRM events

Company, contact and deal events contain the entity after the change in data. Company names use the resolved display name. crm_deal.stage_changed also includes previousStage. crm_follow_up.completed contains id (the deal ID), nextAction, nextActionDate and activityId. crm_activity.created contains the stored activity, including parent IDs, type, body, rich text and details.

Specific actions emit specific events, not an additional updated event. Won and lost deals emit crm_deal.stage_changed. A deal win can also create a customer, link its company and create system activities; each change emits its own event. New system activities also emit crm_activity.created. Repeated actions that change nothing emit no event. CRM entities are archived and restored, not deleted.

CRM changes and delivery records are saved in the same database transaction. A rollback saves neither. Delivery starts only after commit and uses the existing retry process. Existing all-event subscriptions receive CRM events automatically. crm.changed is a historical audit event, not a public webhook event.

Managing webhooks via the API

Everything the webhooks page does — creating endpoints, rotating secrets, listing deliveries — is also available on the REST API through the webhooks router. It is an administrative router, so it requires an admin-level API key.

API keys →