Webhooks
Webhooks provide a real-time notification mechanism so that you can keep track of your projects without polling our API.
When a subscribed event occurs, Taskrabbit will send an HTTP POST request with a JSON payload to your configured endpoint.
Webhooks are delivered via Svix. Your endpoint URL and event subscriptions are configured in the Svix Partner Dashboard provided to you during onboarding. Svix handles retry logic, delivery logs, and endpoint management.
Payload Structure
All webhook payloads share the following common fields:
| Field | Type | Required | Description |
|---|---|---|---|
| event | string | ✅ Yes | The event type name (e.g. project.completed). |
| project_uuid | string (UUID) | ✅ Yes | The unique identifier for the project this event relates to. |
| timestamp | string (ISO 8601) | ✅ Yes | The datetime the event was processed. |
| agreement_external_reference | string | No | Your own reference ID for the project, if one was provided at project creation. |
Additional fields specific to each event type are described in the sections below.
─────────────────────────────────────────────────────
Events
The following events are available for subscription in the Svix Partner Dashboard:
| Event Name | Description |
|---|---|
| project.completed | A project's work has been completed by the Tasker. |
| project.canceled | A project has been canceled. |
| project.rescheduled | A project has been rescheduled to a new start time. |
─────────────────────────────────────────────────────
project.completed
Fired when a project's work has been marked as completed.
Payload
| Field | Type | Required | Description |
|---|---|---|---|
| event | string | ✅ Yes | Always "project.completed". |
| project_uuid | string (UUID) | ✅ Yes | The unique identifier for the completed project. |
| timestamp | string (ISO 8601) | ✅ Yes | The datetime the completion event was processed. |
| agreement_external_reference | string | No | Your reference ID for this project, if provided. |
Example
{ "event": "project.completed", "project_uuid": "550e8400-e29b-41d4-a716-446655440000", "timestamp": "2025-01-22T10:00:00Z", "agreement_external_reference": "REF-12345" }
───────────────────────────────────────────────
project.canceled
Fired when a project has been canceled. Includes a reason code indicating why the cancellation occurred.
Payload
| Field | Type | Required | Description |
|---|---|---|---|
| event | string | ✅ Yes | Always "project.canceled". |
| project_uuid | string (UUID) | ✅ Yes | The unique identifier for the canceled project. |
| cancellation_reason | string (enum) | ✅ Yes | The reason the project was canceled. See Cancellation Reasons below. |
| timestamp | string (ISO 8601) | ✅ Yes | The datetime the cancellation occurred. |
| agreement_external_reference | string | No | Your reference ID for this project, if provided. |
Cancellation Reasons
| Reason | Description |
|---|---|
| order_canceled | The order was canceled by the partner or client. |
| delivery_delayed | The project was canceled due to a delivery delay. |
| changed_mind | The client changed their mind and canceled. |
| canceled_by_cs | The project was canceled by Taskrabbit Customer Support. |
Example
{ "event": "project.canceled", "project_uuid": "550e8400-e29b-41d4-a716-446655440000", "cancellation_reason": "order_canceled", "timestamp": "2025-01-22T10:00:00Z", "agreement_external_reference": "REF-12345" }
───────────────────────────────────────────────
project.rescheduled
Fired when a task within a project has been rescheduled to a new start time. Both the new and previous scheduled times are included so you can reconcile the change in your own system.
Payload
| Field | Type | Required | Description |
|---|---|---|---|
| event | string | ✅ Yes | Always "project.rescheduled". |
| project_uuid | string (UUID) | ✅ Yes | The unique identifier for the project whose task was rescheduled. |
| new_start_time | string (ISO 8601) | ✅ Yes | The newly scheduled start time for the task. |
| previous_start_time | string (ISO 8601) | ✅ Yes | The start time the task was previously scheduled for. |
| timestamp | string (ISO 8601) | ✅ Yes | Set to the value of new_start_time. |
| agreement_external_reference | string | No | Your reference ID for this project, if provided. |
Example
{ "event": "project.rescheduled", "project_uuid": "550e8400-e29b-41d4-a716-446655440000", "new_start_time": "2025-06-15T09:15:00Z", "previous_start_time": "2025-06-15T07:00:00Z", "timestamp": "2025-06-15T09:15:00Z", "agreement_external_reference": "REF-12345" }
─────────────────────────────────────────────────────
Security & Verification
Svix signs every webhook payload with a secret key unique to your endpoint. You should always verify the signature before processing the payload. Verification libraries are available for most languages in the Svix documentation.
Unverified webhooks should be discarded.
Retries
If your endpoint returns a non-2xx HTTP status code or does not respond within the timeout window, Svix will automatically retry delivery with exponential backoff. You can view delivery attempts and manually replay events from your Svix Partner Dashboard.
To avoid duplicate processing, we recommend making your webhook handler idempotent — i.e., processing the same event more than once should produce the same result.
Updated 9 days ago