Basecamp can notify your application through webhooks when something is changed. A webhook consists of a payload URL to be called, which must be HTTPS, and a list of types that'll trigger calls.
Basecamp will attempt to call the payload URL up to 10 times before deactivating the webhook. The duration between attempts will grow exponentially longer to give your service time to recover. Basecamp will only consider a HTTP status code in the 2xx range to be a successful response. We will not follow a 3xx redirect.
A webhook can be subscribed to updates from the types detailed below. The default is to subscribe to all of them.
Endpoints:
- Comment
- Client::Approval::Response
- Client::Forward
- Client::Reply
- CloudFile
- Document
- GoogleDocument
- Inbox::Forward
- Kanban::Card
- Kanban::Step
- Message
- Question
- Question::Answer
- Schedule::Entry
- Todo
- Todolist
- Upload
- Vault
Note that chat isn't amongst the options. Check our chat bot API for that. Also, CloudFile type corresponds to files linked from any cloud provider different from Google Drive (which has its separate GoogleDocument type).
Whenever an event is created for any of the types that webhook was created to match, Basecamp will call your payload URL. All payloads follow the same JSON format:
{
"id": 9007199254741210,
"kind": "message_created",
"details": { "notified_recipient_ids": [1007299144] },
"created_at": "2016-06-08T19:00:41.933Z",
"recording": {
"id": 9007199254741622,
"status": "active",
"created_at": "2016-07-20T00:21:41.446Z",
"updated_at": "2016-07-19T21:29:08.739Z",
"title": "Welcome to Basecamp!",
"inherits_status": true,
"type": "Message",
"url": "https://3.basecampapi.com/195539477/buckets/2085958498/messages/9007199254741622.json",
"app_url": "https://3.basecamp.com/195539477/buckets/2085958498/messages/9007199254741622",
"comments_count": 1,
"comments_url": "https://3.basecampapi.com/195539477/buckets/2085958498/recordings/9007199254741622/comments.json",
"parent": {
"id": 9007199254741434,
"title": "Message Board",
"type": "Message::Board",
"url": "https://3.basecampapi.com/195539477/buckets/2085958498/message_boards/9007199254741434.json",
"app_url": "https://3.basecamp.com/195539477/buckets/2085958498/message_boards/9007199254741434"
},
"bucket": {
"id": 2085958498,
"name": "The Leto Laptop",
"type": "Project"
},
"creator": {
"id": 1007299165,
"attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDA3Mjk5MTY1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--c28a27d0c490353fc1a5c2a50ce8eda0fae07370",
"name": "Matt Donahue",
"email_address": "matt@honchodesign.com",
"personable_type": "User",
"title": "Global Data Strategist",
"bio": null,
"created_at": "2016-07-19T21:27:47.654Z",
"updated_at": "2016-07-19T21:27:47.654Z",
"admin": false,
"owner": false,
"time_zone": "America/Chicago",
"avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBF0qCjw=--21513efb0cf6f64f7a0720b2c56ac6145ae6680c/avatar-64-x4"
},
"content": "<div>Hey all, here are some high res shots of the laptop hardware that we can use. These are not public yet, so be careful with how you share them. We don't want any leaks at all with these images.</div>"
},
"creator": {
"id": 1007299165,
"attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDA3Mjk5MTY1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--c28a27d0c490353fc1a5c2a50ce8eda0fae07370",
"name": "Matt Donahue",
"email_address": "matt@honchodesign.com",
"personable_type": "User",
"title": "Global Data Strategist",
"bio": null,
"created_at": "2016-07-19T21:27:47.654Z",
"updated_at": "2016-07-19T21:27:47.654Z",
"admin": false,
"owner": false,
"time_zone": "America/Chicago",
"avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBF0qCjw=--21513efb0cf6f64f7a0720b2c56ac6145ae6680c/avatar-64-x4"
}
}As you'll note, the recording format is the basic generic format that all other content endpoints share, with the addition of a content field. This format won't include as many details about the recording as other specific endpoints return. For example, for a todo, this won't include fields such as description, completed or assignees.
The payload for copy/move events will also include some details on the copied recording under "copy". For example:
{
"id":1479523571,
"kind":"todo_copied",
"details":{
"copy_id":981721240
},
"created_at":"2018-03-23T10:19:33.908+01:00",
"copy":{
"id":981721240,
"url":"https://3.basecampapi.com/195539477/buckets/2085958499/todos/981721240.json",
"app_url":"https://3.basecamp.com/195539477/buckets/2085958499/todos/981721240",
"bucket":{
"id":2085958499,
}
},
"recording":{
"id":968814335,
"status":"active",
"created_at":"2018-03-16T12:17:04.938+01:00",
"updated_at":"2018-03-19T09:31:12.753+01:00",
"title":"Go cutting edge: iOS8 and Android 4.5 only",
"inherits_status": true,
"type":"Todo",
"url":"https://3.basecampapi.com/195539477/buckets/68833643212/todos/968814335.json",
"app_url":"https://3.basecamp.com/195539477/buckets/68833643212/todos/968814335",
"bookmark_url":"https://3.basecampapi.com/195539477/my/bookmarks/BAh7CEkiCGdpZAY6BkVUSSItZ2lkOi8vYmMzL1JlY29yZGluZy85Njg4MTQzMzU_ZXhwaXJlc19pbgY7AFRJIgxwdXJwb3NlBjsAVEkiDXJlYWRhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--9c496c78316f7ff7c52fbbbc957f198efd1c338c.json",
"parent":{
"id":968814030,
"title": "Strategy ideas",
"type":"Todolist",
"url":"https://3.basecampapi.com/195539477/buckets/68833643212/todolists/968814030.json",
"app_url":"https://3.basecamp.com/195539477/buckets/68833643212/todolists/968814030"
},
"bucket":{
"id":68833643212,
"name":"The Leto Laptop",
"type":"Project"
},
"creator": {
"id": 1049715915,
"attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--5f103c46d4f123f0068fcd0192a0f7fea7f26193",
"name": "Annie Bryan",
"email_address": "annie@honchodesign.com",
"personable_type": "User",
"title": "Central Markets Manager",
"bio": "To open a store is easy, to keep it open is an art",
"created_at": "2018-02-14T17:02:25.043Z",
"updated_at": "2018-02-14T17:02:25.043Z",
"admin": false,
"owner": false,
"time_zone": "America/Chicago",
"avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMtkkT4=--e609ef146e39f9ca5e4bb7242fdfd50aec4c3b3f/avatar-64-x4",
"company": {
"id": 1033447817,
"name": "Honcho Design"
}
},
"content":"Go cutting edge: iOS8 and Android 4.5 only"
},
"creator": {
"id": 1049715915,
"attachable_sgid": "BAh7CEkiCGdpZAY6BkVUSSIrZ2lkOi8vYmMzL1BlcnNvbi8xMDQ5NzE1OTE1P2V4cGlyZXNfaW4GOwBUSSIMcHVycG9zZQY7AFRJIg9hdHRhY2hhYmxlBjsAVEkiD2V4cGlyZXNfYXQGOwBUMA==--5f103c46d4f123f0068fcd0192a0f7fea7f26193",
"name": "Annie Bryan",
"email_address": "annie@honchodesign.com",
"personable_type": "User",
"title": "Central Markets Manager",
"bio": "To open a store is easy, to keep it open is an art",
"created_at": "2018-02-14T17:02:25.043Z",
"updated_at": "2018-02-14T17:02:25.043Z",
"admin": false,
"owner": false,
"time_zone": "America/Chicago",
"avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMtkkT4=--e609ef146e39f9ca5e4bb7242fdfd50aec4c3b3f/avatar-64-x4",
"company": {
"id": 1033447817,
"name": "Honcho Design"
}
}
}After sending the payload, Basecamp will record the interaction with your application as a delivery record that can be introspected for debugging. The delivery record includes the full request and response that occurred for that specific event relay.
Basecamp will send the following lifecycle events for all types, here using message as an example:
- message_created / message_active
- message_title_updated / message_content_updated
- message_copied / message_inserted
- message_archived / message_unarchived
- message_trashed / message_untrashed
- message_deleted
There are also a handful of shared operations around the types that pertain to all types, again using message as an example:
- message_subscribers_changed
- message_publicized
Comments added on any recording will trigger the following event:
- comment_created
Additionally, some types have unique events. They are as follows:
Todos:
- todo_completed
- todo_uncompleted
Questions:
- question_paused
- question_resumed
Starting the 1st of July 2024, Basecamp won't notify of changes that are automatically propagated to children's recordings. For example, when archiving a todolist, all its contained todos and comments within each todo will get archived too. In this case, Basecamp will only notify the status change on the parent todolist, not on each of the contained items.
Note: client users aren't allowed to perform any of the webhook related actions, so calling these endpoints while being authenticated with a client user will get a 403 Forbidden response.
GET /buckets/1/webhooks.jsonwill return all the webhooks for the project with an ID of1.
[
{
"id": 1051369971,
"active": false,
"created_at": "2026-02-12T06:11:41.608Z",
"updated_at": "2026-02-12T06:11:41.608Z",
"payload_url": "https://example.com/endpoint",
"types": [
"all"
],
"url": "https://3.basecampapi.com/195539477/buckets/2085958504/webhooks/1051369971.json",
"app_url": "https://3.basecamp.com/195539477/buckets/2085958504/webhooks/1051369971"
}
]curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/webhooks.jsonGET /webhooks/3.jsonwill return the webhook with an ID of3.
The recent deliveries array will contain the 25 most recent delivery exchanges, sorted with the most recent first.
{
"id": 1051369971,
"active": false,
"created_at": "2026-02-12T06:11:41.608Z",
"updated_at": "2026-02-12T06:11:41.608Z",
"payload_url": "https://example.com/endpoint",
"types": [
"all"
],
"url": "https://3.basecampapi.com/195539477/buckets/2085958504/webhooks/1051369971.json",
"app_url": "https://3.basecamp.com/195539477/buckets/2085958504/webhooks/1051369971",
"recent_deliveries": [
{
"id": 627138718,
"created_at": "2026-02-12T06:14:15.773Z",
"request": {
"headers": {
"Content-Type": "application/json",
"User-Agent": "Basecamp3 Webhook",
"X-Request-Id": "3845f9bd-2b8a-4c08-9f30-c01135ab2f23"
},
"body": {
"id": 1071915703,
"kind": "message_subscribers_changed",
"details": {
"added_person_ids": [
1049715939
],
"removed_person_ids": [
1049715913
]
},
"created_at": "2026-02-12T00:14:14.701-06:00",
"recording": {
"id": 1069479406,
"status": "active",
"visible_to_clients": false,
"created_at": "2025-12-30T12:58:00.000-06:00",
"updated_at": "2026-02-12T00:14:14.697-06:00",
"title": "We won Leto!",
"inherits_status": true,
"type": "Message",
"url": "https://3.basecampapi.com/195539477/buckets/2085958504/messages/1069479406.json",
"app_url": "https://3.basecamp.com/195539477/buckets/2085958504/messages/1069479406",
"bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7BkkiC19yYWlscwY6BkVUewdJIglkYXRhBjsAVEkiLmdpZDovL2JjMy9SZWNvcmRpbmcvMTA2OTQ3OTQwNj9leHBpcmVzX2luBjsAVEkiCHB1cgY7AFRJIg1yZWFkYWJsZQY7AFQ=--309e0fbab86893aaaf279f01f2a0795c56716aeb.json",
"subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958504/recordings/1069479406/subscription.json",
"parent": {
"id": 1069479392,
"title": "Message Board",
"type": "Message::Board",
"url": "https://3.basecampapi.com/195539477/buckets/2085958504/message_boards/1069479392.json",
"app_url": "https://3.basecamp.com/195539477/buckets/2085958504/message_boards/1069479392"
},
"bucket": {
"id": 2085958504,
"name": "The Leto Laptop",
"type": "Project"
},
"creator": {
"id": 1049715913,
"attachable_sgid": "BAh7BkkiC19yYWlscwY6BkVUewdJIglkYXRhBjsAVEkiK2dpZDovL2JjMy9QZXJzb24vMTA0OTcxNTkxMz9leHBpcmVzX2luBjsAVEkiCHB1cgY7AFRJIg9hdHRhY2hhYmxlBjsAVA==--e627c45e6b34e08862da23906862412620e4d5d9",
"name": "Victor Cooper",
"email_address": "victor@honchodesign.com",
"personable_type": "User",
"title": "Chief Strategist",
"bio": "Don’t let your dreams be dreams",
"location": "Chicago, IL",
"created_at": "2026-02-12T00:08:49.342-06:00",
"updated_at": "2026-02-12T00:08:50.871-06:00",
"admin": true,
"owner": true,
"client": false,
"employee": true,
"time_zone": "America/Chicago",
"avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMlkkT4=--5fe7b70fbee7a7f0e2e1e19df7579e5d880c753d/avatar?v=1",
"company": {
"id": 1033447817,
"name": "Honcho Design"
},
"can_ping": true,
"can_manage_projects": true,
"can_manage_people": true,
"can_access_timesheet": false,
"can_access_hill_charts": true
},
"content": "Hey guys,<br><br>We won the Leto account! This is huge for us, it really marks a turning point for the company.<br><br>As you know we've been pursuing bigger clients in the consumer space, but we've done so carefully. We've never been about getting the biggest clients - those are easy to get. We've been trying to get the best clients for us - ones that will challenge us, grow us, make us better, and ultimately giving us a platform to show how awesome you guys all are. And now we have that!<br><br>A big congrats to everyone who worked so hard to make this happen, and now the fun really begins. Most of the pitch team will stay on as leading members of the first project, the Leto Microsite.<br><br>Again, great job everyone, and let's go kick some more butt!<br><br>-Victor<br>"
},
"creator": {
"id": 1049715913,
"attachable_sgid": "BAh7BkkiC19yYWlscwY6BkVUewdJIglkYXRhBjsAVEkiK2dpZDovL2JjMy9QZXJzb24vMTA0OTcxNTkxMz9leHBpcmVzX2luBjsAVEkiCHB1cgY7AFRJIg9hdHRhY2hhYmxlBjsAVA==--e627c45e6b34e08862da23906862412620e4d5d9",
"name": "Victor Cooper",
"email_address": "victor@honchodesign.com",
"personable_type": "User",
"title": "Chief Strategist",
"bio": "Don’t let your dreams be dreams",
"location": "Chicago, IL",
"created_at": "2026-02-12T00:08:49.342-06:00",
"updated_at": "2026-02-12T00:08:50.871-06:00",
"admin": true,
"owner": true,
"client": false,
"employee": true,
"time_zone": "America/Chicago",
"avatar_url": "https://3.basecamp-static.com/195539477/people/BAhpBMlkkT4=--5fe7b70fbee7a7f0e2e1e19df7579e5d880c753d/avatar?v=1",
"company": {
"id": 1033447817,
"name": "Honcho Design"
},
"can_ping": true,
"can_manage_projects": true,
"can_manage_people": true,
"can_access_timesheet": false,
"can_access_hill_charts": true
}
}
},
"response": {
"headers": {
"Content-Type": "application/json"
},
"code": 200,
"message": "OK",
"body": "{}"
}
}
]
}curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/webhooks/3.jsonPOST /buckets/1/webhooks.jsoncreates a webhook in the project with an ID of1.
Required parameters: payload_url for the HTTPS url that Basecamp should call.
Optional parameters: types as an array of types, options given in the introduction.
This endpoint will return 201 Created with the current JSON representation of the webhook if the creation was a success. See the Get a webhook endpoint for more info on the payload.
This endpoint will return 400 Bad Request if the payload URL is not a valid HTTPS URL or other validation errors occur. It will return 507 Insufficient Storage if the account has reached its webhook limit.
{
"payload_url": "https://example.com/endpoint",
"types": [ "Todo", "Todolist" ]
}curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
-d '{"payload_url":"https://example.com/endpoint","types":["Todo","Todolist"]}' \
https://3.basecampapi.com/$ACCOUNT_ID/buckets/1/webhooks.jsonPUT /webhooks/3.jsonallows changing the payload url and types of the webhook with an ID of3.
Required parameters: payload_url for the HTTPS url that Basecamp will call.
Optional parameters: types as an array of types, options given in the introduction. active as a boolean whether this webhook should be matching.
This endpoint will return 200 OK with the current JSON representation of the webhook if the update was a success. See the Get a webhook endpoint for more info on the payload.
This endpoint will return 400 Bad Request if the payload URL is not a valid HTTPS URL or other validation errors occur.
{
"payload_url": "https://example.com/endpoint",
"types": ["Todo", "Todolist"],
"active": true
}curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
-d '{"payload_url":"https://example.com/endpoint","types":["Todo","Todolist"],"active":true}' -X PUT \
https://3.basecampapi.com/$ACCOUNT_ID/webhooks/3.jsonDELETE /webhooks/3.jsonwill delete the webhook with an ID of3.
This endpoint will return 204 No Content if the destroy was a success.
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE \
https://3.basecampapi.com/$ACCOUNT_ID/webhooks/3.jsonThe following project-scoped routes are still supported and will remain available, but flat routes above are the canonical form for new integrations.
GET /buckets/1/webhooks/3.json→ Get a webhookPUT /buckets/1/webhooks/3.json→ Update a webhookDELETE /buckets/1/webhooks/3.json→ Destroy a webhook