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.

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.

Payload format

folk webhooks send a thin payload 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:

string

required

The unique identifier of the webhook event.

type

string

required

The event type that occurred.

createdAt

string

required

The date and time the event occurred, in ISO 8601 format.

source

string

required

The API URL of the webhook that delivered the event.

data

object

required

The data of the webhook delivery. It contains the properties that help identify the resource that the event occurred on.

Show child properties

string

required

The unique identifier of the resource that the event occurred on, eg: person id, company, id, deal id, etc.

url

string

required

The API URL of the resource that the event occurred on. You can use this URL to fetch the full details of the resource.

changes

array

An array of objects that describe the attributes that changed. This is usually only included for events triggered by updates to a resource.

Show child properties

path

array

required

The path of the attribute that changed, in array format.

type

string

required

The type of change that occurred. Possible values are: add, remove, set.

value

unknown

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.

details

object

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.

Delivery example

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

person.created

This event occurs when a person is created in the workspace.Example:

{
  "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"
  }
}

person.updated

This event occurs when a person’s native attributes or custom fields are updated.Example:

{
  "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.

person.deleted

This event occurs when a person is deleted from the workspace.Example:

{
  "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"]
    }
  }
}

person.groups_updated

This event occurs when a person’s groups are updated.Example:

{
  "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" }]
      }
    ]
  }
}

person.workspace_interaction_metadata_updated

This event occurs when a person’s workspace interaction metadata is updated.Example:

{
  "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

company.created

This event occurs when a company is created in the workspace.Example:

{
  "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"
  }
}

company.updated

This event occurs when a company’s native attributes or custom fields are updated.Example:

{
  "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.

company.deleted

This event occurs when a company is deleted from the workspace.Example:

{
  "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"]
    }
  }
}

company.groups_updated

This event occurs when a company’s groups are updated.Example:

{
  "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

object.created

This event occurs when a deal is created in the workspace.Example:

{
  "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"
  }
}

object.updated

This event occurs when a deal is updated in the workspace.Example:

{
  "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" }]
      }
    ]
  }
}

object.deleted

This event occurs when a deal is deleted from the workspace.Example:

{
  "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

note.created

This event occurs when a note is created in the workspace.Example:

{
  "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"
  }
}

note.updated

This event occurs when a note is updated in the workspace.Example:

{
  "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.

note.deleted

This event occurs when a note is deleted from the workspace.Example:

{
  "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

reminder.created

This event occurs when a reminder is created in the workspace.Example:

{
  "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"
  }
}

reminder.updated

This event occurs when a reminder is updated in the workspace.Example:

{
  "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" }
        ]
      }
    ]
  }
}

reminder.deleted

This event occurs when a reminder is deleted from the workspace.Example:

{
  "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"
      }
    }
  }
}

reminder.triggered

This event occurs when a reminder is triggered in the workspace.Example:

{
  "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 and update a webhook API references for more information.

Get started

Core concepts

Use cases

Webhooks

Delivery headers

Payload format

Event list

Person events

Company events

Deal events

Note events

Reminder events

Filtering events

​Delivery headers

​Payload format

​Event list

​Person events

​Company events

​Deal events

​Note events

​Reminder events

​Filtering events

Delivery headers

Payload format

Event list

Person events

Company events

Deal events

Note events

Reminder events

Filtering events