Webhooks overview
Webhooks push workspace events to your own HTTPS endpoint in near real time. Available on the Agency plan for Owners and Admins.
Webhooks let Hoursmith push events from your workspace to your own HTTPS endpoint as things happen — an invoice is paid, a time entry is logged, a task is completed. Instead of polling the API on a schedule, your systems react the moment an event occurs.
- Plan
- Agency
- Role
- OwnerAdmin
Webhooks require the Agency plan (the outboundWebhooks entitlement) and are configured by an
Owner or Admin. On Free and Studio you'll see an upgrade prompt — see
Plans & limits and
Billing & plans.
How it works
When something happens in your workspace, Hoursmith builds an event, wraps it in a JSON
envelope, signs it, and POSTs it to every endpoint subscribed to that event type.
- Something happens — for example, a client pays an invoice.
- An event is created with a stable
id, atype, and adatasnapshot of the affected resource. - Hoursmith delivers it as an HTTP
POSTwithContent-Type: application/jsonand aHoursmith-Signatureheader. - Your endpoint verifies the signature, returns a 2xx response quickly, and processes the event.
- If delivery fails, Hoursmith retries with backoff.
Deliveries are signed but not encrypted beyond TLS. Always use an HTTPS endpoint and verify the signature before trusting a payload.
What you can subscribe to
Hoursmith emits 8 event types across invoices, time entries, tasks, clients, and projects:
| Event | Fires when |
|---|---|
invoice.sent | An invoice is sent to a client. |
invoice.paid | An invoice is marked paid. |
invoice.payment_failed | A payment attempt on an invoice fails. |
time_entry.created | A time entry is created. |
task.completed | A task is marked complete. |
task.created | A task is created. |
client.created | A client is created. |
project.created | A project is created. |
There are no wildcard subscriptions in v1 — subscribe to each event type you want. See
Event types & payloads for the full envelope and data shapes.
Best practices
- Return 2xx fast, process async. Acknowledge the delivery immediately and do the real work in a background job. Your endpoint has roughly a 10-second budget.
- Verify every signature using the
Hoursmith-Signatureheader before acting on a payload. - Dedupe on the event
id. Retries reuse the sameid, so an idempotent handler prevents double-processing. - Use HTTPS for your endpoint URL.
- Keep your signing secret out of source control. Store it in an environment variable or a secrets manager.
Get started
Create an endpoint
Add a URL, pick events, and grab your signing secret.
Event types & payloads
The 8 events and the envelope they arrive in.
Verify signatures
Validate the Hoursmith-Signature header in Node.js or Python.
Retries & replay
Backoff schedule, idempotency, and replaying deliveries.