Webhook events reference

TimeTracker posts workspace events to your own HTTPS endpoint. This page is the contract: event names, the body, the headers and the delivery rules.

The request

Every delivery is a POST with a JSON body.

{
  "version": 1,
  "event": {
    "key": "timesheet.approved",
    "occurredAt": 1753977600000,
    "workspaceId": "..."
  },
  "deliveryId": "...",
  "data": {
    "workspaceId": "...",
    "ownerUserId": "...",
    "submissionId": "...",
    "approverUserId": "...",
    "periodStart": 1753372800000,
    "periodEnd": 1753977600000
  }
}

Field	What it is
`version`	The body format version. Currently `1`.
`event.key`	The event name, from the table below.
`event.occurredAt`	When the event happened, in epoch milliseconds.
`event.workspaceId`	The workspace the event belongs to.
`deliveryId`	A stable id for this event and this endpoint. Use it to dedupe.
`data`	Stable ids and event-time values for the event. Fields vary by event.

data carries ids and immutable values, not full records. Fetch the record if you need its current state – the payload is a fact about a moment, not a snapshot of your database.

Headers

Header	Value
`content-type`	`application/json`
`X-TimeTracker-Signature`	`t=<unix seconds>,v1=<hex HMAC>`
`X-TimeTracker-Delivery-Id`	The same value as `deliveryId` in the body

Verifying the signature

Each endpoint has its own signing secret, shown once when you create it and again when you rotate it.

Read the header

Split X-TimeTracker-Signature on the comma. You get t=<timestamp> and v1=<hex>.

Build the signed string

Join the timestamp and the raw request body with a full stop: <t>.<raw body>. Use the bytes exactly as received – do not re-serialise the JSON, or the signature will not match.

Compute the HMAC

HMAC-SHA256 the signed string with your endpoint secret, hex-encoded.

Compare

Compare against the v1 value using a constant-time comparison.

Allow a wide timestamp tolerance. A retry reuses the original signature and its original timestamp, so a tolerance of a few seconds rejects every retry. Hours, not seconds.

Deduplicate on `deliveryId`

Delivery is at least once. The same logical event can arrive twice – after a network timeout, or when someone resends it by hand. deliveryId is stable for a given event and endpoint. Store it and ignore a repeat.

Event names

Names are area.event. Sixty-six events are published today.

Timesheets

Event	Fires when
`timesheet.submitted`	A person sends their week for review
`timesheet.approved`	An approver accepts a period
`timesheet.changes_requested`	An approver sends a period back
`timesheet.withdrawn`	A submitter pulls their period back
`timesheet.reopened`	An approved period is reopened
`timesheet.period_closed`	A period is closed and locked
`timesheet.reminder`	A timesheet reminder goes out
`timesheet.not_submitted`	A period passes with nothing submitted
`timesheet.approval_overdue`	A submitted period has waited too long

Time Clock

Event	Fires when
`timecard.submitted`	A person submits a timecard period
`timecard.approved`	A timecard period is approved
`timecard.changes_requested`	A timecard period is sent back
`timecard.correction_approved`	A shift-correction request is accepted
`timecard.correction_rejected`	A shift-correction request is declined
`timecard.missing_clock_out`	A session was never clocked out

Time off

Event	Fires when
`time_off.requested`	Someone asks for leave
`time_off.approved`	A request is approved
`time_off.rejected`	A request is declined
`time_off.withdrawn`	A requester pulls it back
`time_off.approval_withdrawn`	An approver revokes an approval
`time_off.approval_overdue`	A request has waited too long
`time_off.balance_adjusted`	A balance is corrected by hand
`time_off.upcoming`	Approved leave is about to start

Expenses

Event	Fires when
`expense.submitted`	An expense is submitted
`expense.approved`	An expense is approved
`expense.rejected`	An expense is declined
`expense.clarification_requested`	An approver asks a question
`expense.approval_overdue`	An expense has waited too long

Invoices and payments

Event	Fires when
`invoice.created`	An invoice is created
`invoice.sent`	An invoice is sent to a client
`invoice.paid`	An invoice is settled in full
`invoice.overdue`	An invoice passes its due date unpaid
`invoice.voided`	An invoice is voided
`payment.recorded`	A payment is recorded
`payment.reminder_sent`	A payment reminder goes out

Tasks

Event	Fires when
`task.assigned`	A task is assigned to someone
`task.completed`	A task is completed
`task.reopened`	A completed task is reopened
`task.status_changed`	A task moves status
`task.due_soon`	A task’s due date is approaching

Projects

Event	Fires when
`project.status_changed`	A project changes status
`project.archived`	A project is archived
`project.member_added`	Someone joins a project
`project.member_removed`	Someone leaves a project
`project.budget_threshold_reached`	A budget crosses an alert threshold

People and access

Event	Fires when
`member.invited`	An invitation is sent
`member.invitation_accepted`	An invitation is accepted
`member.invitation_revoked`	An invitation is withdrawn
`membership.role_changed`	Someone’s role changes
`membership.removed`	Someone is removed from the workspace
`workspace.member_deleted`	A member’s account is deleted

Client portal

Event	Fires when
`portal.comment_posted`	A client contact comments
`portal.deliverable_approved`	A client approves a deliverable

Reminders and comms

Event	Fires when
`comment.mentioned`	Someone is mentioned in a comment
`reminder.today_agenda`	The morning agenda reminder
`reminder.no_tasks_today`	Nothing is planned for today
`reminder.no_tasks_tomorrow`	Nothing is planned for tomorrow
`reminder.task_deadlines`	The deadline rollup
`notification.digest_summary`	A digest is compiled

Billing, security and exports

Event	Fires when
`billing.subscription_activated`	A subscription becomes active
`billing.trial_ending`	A trial is about to end
`billing.trial_expired`	A trial has ended
`billing.payment_action_required`	A payment needs attention
`security.email_changed`	An account email changes
`security.suspicious_login`	An unusual sign-in is detected
`export.ready`	An export finishes and is ready to download

Filtering what you receive

An endpoint with no filters receives every event. Otherwise you pick from these categories, and an event matches if its own name or its category is in your list.

Filter	Covers
Assignments	Task assignment events
Due soon	Task due-date warnings
Overdue	Overdue warnings
Mentions	Comment mentions
Timesheets	The timesheet workflow
Budget alerts	Budget threshold events
Scope changes	Estimate and scope approval events
Invoices	The invoice and payment workflow
Time off	The leave workflow
Timecard	The Time Clock workflow

Endpoint rules

Rule	Detail
Scheme	HTTPS only
Address	Must be publicly reachable. Private, loopback and cloud metadata addresses are refused.
Redirects	Never followed. A `3xx` response is a failed delivery.
Timing	Events are dispatched about once a minute, so expect delivery within roughly a minute of the event.

Retries and failures

What happens	Detail
A temporary failure	Retried with exponential backoff and jitter, starting at 30 seconds and capping at 1 hour
Retry limit	Up to 6 attempts, then the delivery is given up on
A permanent failure	Given up on immediately – no retries for a rejected URL or a bad response class
Rate limiting	A `Retry-After` response header is honoured, up to the 1-hour cap
A long dead endpoint	After 20 consecutive failed deliveries, the endpoint is switched off until an admin re-enables it
A success	Resets the consecutive-failure count to zero

Return a 2xx quickly. Do your own work after you have acknowledged, not before.

Delivery states you see in the app

Badge	Meaning
Delivered	Your endpoint accepted it
Retrying	A temporary failure, waiting for the next attempt
Pending	Queued, not attempted yet
Failed	Given up on

The endpoint itself shows Active, Failing or Disabled.

When the app is off

Switching the Webhooks & API app off stops deliveries. Events raised while it is off are queued, not dropped, and deliver when you switch it back on. Expect a burst after a long pause.

Permissions

Action	Capability	Roles
Add, edit, delete, rotate or resend	`webhook.manage`	Owner, Admin

Webhooks also need the Webhooks & API app switched on and a Pro plan.

Common questions

Can I see my secret again later?

No. The secret is shown once, when you create the endpoint or rotate it. Store it somewhere safe. If you lose it, rotate to get a new one.

Why did my signature check fail?

Almost always because the body was re-serialised before signing. Sign the raw bytes exactly as received. The second cause is a timestamp tolerance that is too narrow for retries.

Why was my endpoint disabled?

Twenty consecutive failed deliveries. Fix the endpoint, then re-enable it in Settings → Webhooks.

Can I send events to localhost while testing?

No. Private and loopback addresses are refused. Use a public HTTPS tunnel.

How do I test an endpoint?

Send a test delivery from the endpoint’s row in Settings → Webhooks. It uses the same signing and the same headers as a real event.

Webhooks

Setting one up, step by step.

Webhook settings

The screen itself.

Notification types

The same events as in-app and email notices.

Integrations

Everything TimeTracker connects to.

Reference

Help

Webhook events reference

The request

Headers

Verifying the signature

Deduplicate on `deliveryId`

Event names

Timesheets

Time Clock

Time off

Expenses

Invoices and payments

Tasks

Projects

People and access

Client portal

Reminders and comms

Billing, security and exports

Filtering what you receive

Endpoint rules

Retries and failures

Delivery states you see in the app

When the app is off

Permissions

Common questions

Webhooks

Webhook settings

Notification types

Integrations

​The request

​Headers

​Verifying the signature

​Deduplicate on deliveryId

​Event names

​Timesheets

​Time Clock

​Time off

​Expenses

​Invoices and payments

​Tasks

​Projects

​People and access

​Client portal

​Reminders and comms

​Billing, security and exports

​Filtering what you receive

​Endpoint rules

​Retries and failures

​Delivery states you see in the app

​When the app is off

​Permissions

​Common questions

​Related guides

Webhooks

Webhook settings

Notification types

Integrations

The request

Headers

Verifying the signature

Deduplicate on `deliveryId`

Event names

Timesheets

Time Clock

Time off

Expenses

Invoices and payments

Tasks

Projects

People and access

Client portal

Reminders and comms

Billing, security and exports

Filtering what you receive

Endpoint rules

Retries and failures

Delivery states you see in the app

When the app is off

Permissions

Common questions

Related guides