Skip to main content
Webhooks let you connect Arca to external systems by sending an HTTPS POST request to a URL you control whenever something changes, a task is created, a status changes, a list is updated, and more.

​
Create a webhook

  1. Go to Settings → Webhooks.
  2. Click Create your first webhook or Add new webhook.
  3. Fill in the form:
    • Label: a name to help you identify this webhook.
    • Endpoint URL: the URL Arca will POST to. Must use https.
    • Events: select one or more events to subscribe to (see Events below).
    • Workspaces: if you own more than one workspace, choose which ones this webhook applies to. All your workspaces are selected by default.
    • Auth token: optionally generate a secret token so your server can verify requests come from Arca.
  4. Click Create webhook.
Before the webhook is saved, Arca sends a POST request to your endpoint with the header X-Arca-Event: ping and this JSON body: 
{
  "event": "ping",
  "timestamp": "2026-04-05T12:00:00.000Z",
  "workspaceId": null,
  "before": null,
  "after": null,
  "data": {}
}
Your server must respond with a 2xx status code within 10 seconds, otherwise the webhook is not created. Make sure your endpoint is publicly accessible and ready to accept POST requests before submitting. If you enabled the auth token option, the token is shown once immediately after creation. Copy it and store it securely, Arca never shows it again. If you lose it, delete the webhook and create a new one.

​
Events

Every webhook subscribes to one or more event types. Arca sends a delivery only when a subscribed event occurs in one of the webhook’s selected workspaces.

​
Task events

EventTriggered when
task.createdA new task is created
task.deletedA task is deleted
task.status.changedA task’s status is changed
task.priority.changedA task’s priority is changed
task.assignees.changedAssignees are added or removed
task.start_date.changedThe start date is changed
task.due_date.changedThe due date is changed
task.labels.changedLabels are added or removed

​
Folder events

EventTriggered when
folder.createdA new folder is created
folder.updatedA folder is renamed or edited
folder.deletedA folder is deleted
folder.movedA folder is reordered

​
List events

EventTriggered when
list.createdA new list is created
list.updatedA list is renamed or edited
list.deletedA list is deleted

​
Payload

Arca sends a JSON payload as the POST body: 
{
  "event": "task.status.changed",
  "timestamp": "2026-04-05T12:34:56.789Z",
  "workspace": {
    "id": 42,
    "name": "Acme Corp",
    "slug": "acme-corp",
    "avatarUrl": "https://cdn.getarca.app/workspaces/42/avatar.png"
  },
  "user": {
    "id": 7,
    "name": "Alice",
    "avatarUrl": null
  },
  "before": {
    "id": 101,
    "title": "Fix login bug",
    "status": { "id": 1, "name": "Todo", "color": "gray", "category": "pending" },
    "priority": "high",
    "assignees": [{ "id": 7, "name": "Alice", "avatarUrl": null }]
  },
  "after": {
    "id": 101,
    "title": "Fix login bug",
    "status": { "id": 3, "name": "Done", "color": "green", "category": "completed" },
    "priority": "high",
    "assignees": [{ "id": 7, "name": "Alice", "avatarUrl": null }]
  }
}
FieldDescription
eventThe event type string (e.g. task.status.changed)
timestampUTC ISO-8601 timestamp of when the event was dispatched
workspace.idNumeric ID of the workspace where the event occurred
workspace.nameDisplay name of the workspace
workspace.slugURL slug of the workspace
workspace.avatarUrlWorkspace avatar URL, or null if none is set
userThe user who triggered the event, or null when triggered by an automated system
user.idNumeric ID of the actor
user.nameDisplay name of the actor
user.avatarUrlActor avatar URL, or null if none is set
beforeState before the change. null for *.created events
afterCurrent state of the entity. null for *.deleted events
after.assigneesArray of { id, name, avatarUrl } objects. Present on all task.* events

​
Request headers

Arca includes the following headers with every delivery:
HeaderValue
Content-Typeapplication/json
User-AgentArca-Webhooks/1.0
X-Arca-EventThe event type (e.g. task.created)
AuthorizationBearer whs_…, only present if you enabled an auth token

​
Webhook Payloads

The tabs below show the complete JSON body delivered to your endpoint for each event type.

​
Task events

{
  "event": "task.created",
  "timestamp": "2026-04-05T12:00:00.000Z",
  "workspace": {
    "id": 42,
    "name": "Acme Corp",
    "slug": "acme-corp",
    "avatarUrl": null
  },
  "user": {
    "id": 1,
    "name": "Alice",
    "avatarUrl": null
  },
  "before": null,
  "after": {
    "id": 42,
    "identifier": 5,
    "title": "Fix the login bug",
    "priority": "high",
    "status": {
      "id": 3,
      "name": "In Progress",
      "color": "blue",
      "category": "started"
    },
    "list": {
      "id": 7,
      "name": "Sprint 1",
      "icon": "rocket",
      "color": "green"
    },
    "dueDate": "2026-04-10T00:00:00.000Z",
    "startDate": null,
    "assignees": [
      { "id": 1, "name": "Alice", "avatarUrl": null }
    ],
    "labels": [
      { "id": 2, "name": "Bug", "color": "red" }
    ],
    "createdAt": "2026-04-05T12:00:00.000Z"
  }
}

​
Folder events

{
  "event": "folder.created",
  "timestamp": "2026-04-05T12:00:00.000Z",
  "workspace": {
    "id": 42,
    "name": "Acme Corp",
    "slug": "acme-corp",
    "avatarUrl": null
  },
  "user": {
    "id": 1,
    "name": "Alice",
    "avatarUrl": null
  },
  "before": null,
  "after": {
    "id": 12,
    "name": "Design",
    "icon": "folder",
    "color": "blue",
    "position": 0,
    "workspace": {
      "id": 42,
      "name": "Acme Corp",
      "slug": "acme-corp",
      "avatarUrl": null
    },
    "createdAt": "2026-04-05T12:00:00.000Z"
  }
}

​
List events

{
  "event": "list.created",
  "timestamp": "2026-04-05T12:00:00.000Z",
  "workspace": {
    "id": 42,
    "name": "Acme Corp",
    "slug": "acme-corp",
    "avatarUrl": null
  },
  "user": {
    "id": 1,
    "name": "Alice",
    "avatarUrl": null
  },
  "before": null,
  "after": {
    "id": 8,
    "name": "Backlog",
    "icon": "list",
    "color": "gray",
    "position": 0,
    "folder": {
      "id": 12,
      "name": "Design",
      "icon": "folder",
      "color": "blue"
    },
    "createdAt": "2026-04-05T12:00:00.000Z"
  }
}

​
Verifying deliveries

If you configured an auth token, every request from Arca includes: 
Authorization: Bearer whs_4f3a1b9e...
Compare this value against the token you saved at creation time. Reject requests where it doesn’t match.
The auth token is shown only once, at the moment you create the webhook. Store it immediately in a secure location such as an environment variable or a secrets manager.

​
Delivery behaviour

  • Arca expects your endpoint to respond with a 2xx status code within 10 seconds.
  • Deliveries are fire-and-forget, Arca does not retry failed deliveries.
  • Each failed delivery increments a failure counter. After 6 consecutive failures, Arca automatically disables the webhook and sends you an email notification.

​
Re-enabling a disabled webhook

When a webhook is disabled (manually or automatically), a Disabled badge appears on its card in Settings → Webhooks. Toggle the switch to re-enable it. Re-enabling resets the failure counter to zero.

​
Delete a webhook

Click the delete button on a webhook card in Settings → Webhooks and confirm the prompt. Deletion is immediate and cannot be undone. Any in-flight delivery at the time of deletion will still be attempted.