> ## Documentation Index
> Fetch the complete documentation index at: https://developer.folk.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Events & payloads
You can create webhooks that subscribe to the events listed on this page. To limit the number of HTTP requests to your server, you should only subscribe to the specific events that you plan on handling. For more information, see [Creating webhooks](/webhooks/create-webhooks).
## Delivery headers
When folk sends a webhook delivery, it will include the following special headers:
* `webhook-id`: The unique identifier of the webhook event.
* `webhook-timestamp`: The timestamp of the webhook delivery.
* `webhook-signature`: The signature used to verify the authenticity of the webhook delivery. For more information, see [validating webhook deliveries](/webhooks/handle-deliveries#secure-your-handler).
## Payload format
folk webhooks send a [thin payload](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md#thin-vs-full-payloads) with only the necessary information to identify the resource that the event occurred on, and based on the event type, it can optionally include the attributes that changed.
The payload of the webhook delivery is a JSON object that will always contain the following fields:
The unique identifier of the webhook event.
The event type that occurred.
The date and time the event occurred, in ISO 8601 format.
The API URL of the webhook that delivered the event.
The data of the webhook delivery. It contains the properties that help identify the resource that the event occurred on.
The unique identifier of the resource that the event occurred on, eg: person
id, company, id, deal id, etc.
The API URL of the resource that the event occurred on. You can use this URL
to fetch the full details of the resource.
An array of objects that describe the attributes that changed. This
is usually only included for events triggered by updates to a resource.
The path of the attribute that changed, in array format.
The type of change that occurred. Possible values are: `add`, `remove`, `set`.
The value of the attribute that changed. The type of the value depends on the attribute that changed. Check each specific event type for more information.
An object that contains additional details about the event. This is usually only included for events triggered by deletions of resources, as it's not possible to fetch the full details of the resource after it has been deleted.
Please refer to each specific event type for the available properties.
```HTTP theme={null}
POST /payload HTTP/1.1
Content-Type: application/json
webhook-Id: evt_6004f2ef-dcc3-4c56-a704-9326730ad100
webhook-timestamp: 1759226152
webhook-signature: v1,0kZbjDMfF0vDGn14cuOMxL+csZeROynK+YPfMi1RnlE=
Content-Length: 334
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "person.updated",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "per_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/people/per_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"changes": [
{
"path": ["firstName"],
"type": "set",
"value": "John"
},
{
"path": ["customFieldValues", "grp_bc984b3f-0386-434d-82d7-a91eb6badd71", "Status"],
"type": "set",
"value": "In Progress"
},
{
"path": ["customFieldValues", "grp_bc984b3f-0386-434d-82d7-a91eb6badd71", "Tags"],
"type": "remove",
"value": [
"VIP"
]
}
]
}
}
```
## Event list
#### Person events
This event occurs when a person is created in the workspace.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "person.created",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "per_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/people/per_05837e2d-9bf7-4f17-8729-e95f1be4de67"
}
}
```
This event occurs when a person's native attributes or custom fields are updated.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "person.updated",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "per_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/people/per_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"changes": [
{
"path": ["firstName"],
"type": "set",
"value": "John"
},
{
"path": ["description"],
"type": "set"
},
{
"path": ["companies"],
"type": "add",
"value": [
{ "id": "com_3b7d7b65-4c2d-4b65-822a-6bc759e1e951" }
]
}
{
"path": [
"customFieldValues",
"grp_bc984b3f-0386-434d-82d7-a91eb6badd71",
"Status"
],
"type": "set",
"value": "In Progress"
},
{
"path": [
"customFieldValues",
"grp_bc984b3f-0386-434d-82d7-a91eb6badd71",
"Tags"
],
"type": "remove",
"value": [
"VIP"
]
},
{
"path": [
"customFieldValues",
"grp_bc984b3f-0386-434d-82d7-a91eb6badd71",
"Assigned to"
],
"type": "add",
"value": [
{ "id": "usr_3b7d7b65-4c2d-4b65-822a-6bc759e1e951" }
]
}
]
}
}
```
The `description` value is never included in the payload.
This event occurs when a person is deleted from the workspace.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "person.deleted",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "per_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/people/per_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"details": {
"name": "John Doe",
"emails": ["john@doe.com"]
}
}
}
```
This event occurs when a person's groups are updated.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "person.groups_updated",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "per_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/people/per_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"changes": [
{
"path": ["groups"],
"type": "add",
"value": [{ "id": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71" }]
},
{
"path": ["groups"],
"type": "remove",
"value": [{ "id": "grp_3b7d7b65-4c2d-4b65-822a-6bc759e1e951" }]
}
]
}
}
```
This event occurs when a person's workspace interaction metadata is updated.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "person.groups_updated",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "per_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/people/per_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"changes": [
{
"path": ["interactionMetadata", "workspace", "approximateCount"],
"type": "set",
"value": "10"
},
{
"path": ["interactionMetadata", "workspace", "lastInteractedAt"],
"type": "set",
"value": "2025-09-30T09:55:52.715Z"
},
{
"path": ["interactionMetadata", "workspace", "lastInteractedBy"],
"type": "set",
"value": [
{ "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71" },
{ "id": "usr_3b7d7b65-4c2d-4b65-822a-6bc759e1e951" }
]
}
]
}
}
```
#### Company events
This event occurs when a company is created in the workspace.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "company.created",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "com_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/companies/com_05837e2d-9bf7-4f17-8729-e95f1be4de67"
}
}
```
This event occurs when a company's native attributes or custom fields are updated.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "company.updated",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "com_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/companies/com_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"changes": [
{
"path": ["name"],
"type": "set",
"value": "ACME Inc."
},
{
"path": ["description"],
"type": "set"
},
{
"path": [
"customFieldValues",
"grp_bc984b3f-0386-434d-82d7-a91eb6badd71",
"Status"
],
"type": "set",
"value": "In Progress"
},
{
"path": [
"customFieldValues",
"grp_bc984b3f-0386-434d-82d7-a91eb6badd71",
"Tags"
],
"type": "remove",
"value": ["VIP"]
},
{
"path": [
"customFieldValues",
"grp_bc984b3f-0386-434d-82d7-a91eb6badd71",
"Assigned to"
],
"type": "add",
"value": [{ "id": "usr_3b7d7b65-4c2d-4b65-822a-6bc759e1e951" }]
}
]
}
}
```
The `description` value is never included in the payload.
This event occurs when a company is deleted from the workspace.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "company.deleted",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "com_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/companies/com_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"details": {
"name": "ACME Inc.",
"emails": ["hello@acme.com"]
}
}
}
```
This event occurs when a company's groups are updated.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "company.groups_updated",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "com_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/companies/com_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"changes": [
{
"path": ["groups"],
"type": "add",
"value": [{ "id": "grp_bc984b3f-0386-434d-82d7-a91eb6badd71" }]
},
{
"path": ["groups"],
"type": "remove",
"value": [{ "id": "grp_3b7d7b65-4c2d-4b65-822a-6bc759e1e951" }]
}
]
}
}
```
#### Deal events
This event occurs when a deal is created in the workspace.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "object.created",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "obj_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/Deals/obj_05837e2d-9bf7-4f17-8729-e95f1be4de67"
}
}
```
This event occurs when a deal is updated in the workspace.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "object.updated",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "obj_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/Deals/obj_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"changes": [
{
"path": ["name"],
"type": "set",
"value": "New Deal"
},
{
"path": ["customFieldValues", "Status"],
"type": "set",
"value": "In Progress"
},
{
"path": ["customFieldValues", "Tags"],
"type": "remove",
"value": ["VIP"]
},
{
"path": ["customFieldValues", "Assigned to"],
"type": "add",
"value": [{ "id": "usr_3b7d7b65-4c2d-4b65-822a-6bc759e1e951" }]
}
]
}
}
```
This event occurs when a deal is deleted from the workspace.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "object.deleted",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "obj_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/Deals/obj_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"details": {
"name": "Deal with John Doe"
}
}
}
```
#### Note events
This event occurs when a note is created in the workspace.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "note.created",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "nte_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/notes/nte_05837e2d-9bf7-4f17-8729-e95f1be4de67"
}
}
```
This event occurs when a note is updated in the workspace.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "note.updated",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "nte_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/notes/nte_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"changes": [
{
"path": ["visibility"],
"type": "set",
"value": "private"
},
{
"path": ["content"],
"type": "set"
}
]
}
}
```
The `content` value is never included in the payload.
This event occurs when a note is deleted from the workspace.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "note.deleted",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "nte_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/notes/nte_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"details": {
"entity": {
"id": "per_3b7d7b65-4c2d-4b65-822a-6bc759e1e951"
}
}
}
}
```
#### Reminder events
This event occurs when a reminder is created in the workspace.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "reminder.created",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "rmd_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/reminders/rmd_05837e2d-9bf7-4f17-8729-e95f1be4de67"
}
}
```
This event occurs when a reminder is updated in the workspace.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "reminder.updated",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "rmd_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/reminders/rmd_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"changes": [
{
"path": ["name"],
"type": "set",
"value": "New Reminder"
},
{
"path": ["visibility"],
"type": "set",
"value": "private"
},
{
"path": ["assignedUsers"],
"type": "set",
"value": [
{ "id": "usr_3b7d7b65-4c2d-4b65-822a-6bc759e1e951" },
{ "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71" }
]
}
]
}
}
```
This event occurs when a reminder is deleted from the workspace.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "reminder.deleted",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "rmd_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/reminders/rmd_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"details": {
"name": "Weekly meeting with John Doe",
"entity": {
"id": "per_3b7d7b65-4c2d-4b65-822a-6bc759e1e951"
}
}
}
}
```
This event occurs when a reminder is triggered in the workspace.
Example:
```json theme={null}
{
"id": "evt_6004f2ef-dcc3-4c56-a704-9326730ad100",
"type": "reminder.triggered",
"createdAt": "2025-09-30T09:55:52.715Z",
"source": "https://api.folk.app/v1/webhooks/wbk_2f15ec4f-0f70-4884-a43d-1f88ef7a6665",
"data": {
"id": "rmd_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"url": "https://api.folk.app/v1/reminders/rmd_05837e2d-9bf7-4f17-8729-e95f1be4de67",
"changes": [
{
"path": ["lastTriggeredTime"],
"type": "set",
"value": "2025-09-30T09:55:52.715Z"
}
{
"path": ["nextTriggeredTime"],
"type": "set",
"value": "2025-10-30T09:55:52.715Z"
}
]
}
}
```
## Filtering events
Through the API, it is also possible to add filters to events in order to narrow down the notifications you receive.
Filters allow you to achieve advanced workflow capabilities, such as:
* Only receive notifications when a person is added to a specific group.
* Only receive notifications when a company is moved to a specific pipeline status.
* Only receive notifications when a deal from a specific group is updated.
Each event type has a different set of filters that can be used. Refer to the [create a webhook](/api-reference/webhooks/create-a-webhook#filters) and [update a webhook](/api-reference/webhooks/update-a-webhook#filters) API references for more information.