Webhook events and what they contain

Every Notiondesk webhook event you can pick, the request format your server receives, and what data contains for each event.

8 min read

Each webhook request tells you what happened in your workspace or one of its help centers. This article lists every event you can pick for an endpoint, what each request looks like and what it contains.

Quick path: Pick events in Settings > Developers > Webhooks, under Events on an endpoint. Each request is a JSON POST with id, event, version, occurred_at, site_id and data.

Events you can pick

The dashboard groups events the same way as the tables below. The first column is the name you see in the event picker. The second is the event name your server receives in event.

Contacts

In the dashboardEventSent when
Contact message receivedcontact_message.createdA visitor sends your contact form

Content

In the dashboardEventSent when
Article createdarticle.createdA new article, or a new language of an article, is added
Article updatedarticle.updatedAn article's content changes during a sync
Article publishedarticle.publishedA language of an article is published
Article unpublishedarticle.unpublishedA published language of an article is no longer published
Article deletedarticle.deletedAn article is deleted
Article translatedarticle.translatedAn article is translated automatically into a new language
Reaction addedarticle.reaction.addedA reader reacts to an article
Reaction changedarticle.reaction.changedA reader changes their reaction
Reaction removedarticle.reaction.removedA reader removes their reaction
Article feedback receivedarticle.feedback.createdA reader sends written feedback on an article
Category createdcategory.createdA new category, or a new language of a category, is added
Category updatedcategory.updatedA category's content changes during a sync
Category deletedcategory.deletedA category is deleted
Changelog entry publishedchangelog.publishedAn article in a changelog category is published
Sync completedsync.completedA sync with Notion finishes
Sync failedsync.failedA sync with Notion fails

article.updated and category.updated are not sent when only the status or other properties change. Category events are sent once per language.

Reactions and article feedback are capped at 120 events per minute for each help center. Events over the cap are not sent, so use your help center analytics for totals.

Help center settings

In the dashboardEventSent when
Help center settings savedsite.updatedA help center setting is saved
Custom code savedsite.custom_code.updatedCustom CSS or JavaScript is saved
Custom domain verifiedsite.domain.verifiedYour custom domain starts serving the help center
Custom domain check failedsite.domain.verification_failedYour custom domain could not be reached
Integration updatedintegration.updatedAn integration is set up, changed, turned on or turned off
Notion connectednotion.connectedNotion is connected
Notion disconnectednotion.disconnectedNotion is disconnected
Notion access lostnotion.access_lostNotiondesk can no longer read your Notion pages
AI chatbot updatedchatbot.updatedThe chatbot's settings change, or it is turned on or off
Chatbot guidance addedchatbot.guidance.createdA guidance is added to the chatbot
Chatbot guidance updatedchatbot.guidance.updatedA guidance changes
Chatbot guidance deletedchatbot.guidance.deletedA guidance is deleted
Redirect addedredirect.createdA redirect is added
Redirect updatedredirect.updatedA redirect changes
Redirect deletedredirect.deletedA redirect is deleted

Custom domains are checked regularly, so domain events can arrive a few minutes after the change.

Workspace

Workspace events are not tied to one help center, so their site_id is null.

In the dashboardEventSent when
Workspace renamedworkspace.updatedThe workspace is renamed
Join request receivedworkspace.join_request.createdSomeone asks to join the workspace
Join request approvedworkspace.join_request.approvedA join request is approved
Join request declinedworkspace.join_request.declinedA join request is declined
Teammate invitedteam_member.invitedA teammate is invited
Teammate joinedteam_member.joinedAn invited teammate accepts
Teammate role changedteam_member.role_changedA teammate's role changes
Teammate turned on or offteam_member.status_changedA teammate is turned on or off
Teammate removedteam_member.removedA teammate is removed
Teammate signed inteam_member.logged_inA teammate signs in. Sent only to the workspace they open by default
API key createdapi_key.createdAn API key is created
API key rotatedapi_key.rotatedAn API key is rotated
API key revokedapi_key.revokedAn API key is revoked
Help center createdsite.createdA help center is created
Help center deletedsite.deletedA help center is deleted while the workspace still has another online help center

Test event

In the dashboardEventSent when
Test eventpingYou click Send test event on an endpoint

You can't pick ping in the event list. It goes only to the endpoint you test, its site_id is null, and it is sent once, with no retries.

What each request contains

Notiondesk sends a POST request with a JSON body:

{
  "id": "019a8f2e-4b1c-7d3e-9f40-5a6b7c8d9e01",
  "event": "article.published",
  "version": "2026-11-06",
  "occurred_at": "2026-11-17T14:32:05+00:00",
  "site_id": "019a8f2e-0b7d-7c3a-9e15-4f2a6b8c0d11",
  "data": {
    "article": {
      "id": "1763391842",
      "locale": "en",
      "title": "Reset your password",
      "slug": "reset-your-password",
      "url": "https://help.acme-support.com/en/articles/reset-your-password",
      "status": "published"
    }
  }
}
FieldWhat it is
idThe event's ID. It stays the same when a request is retried, so use it to spot duplicates
eventThe event name, for example article.published
versionThe version of this request format
occurred_atWhen the event happened, as an ISO 8601 date and time
site_idThe help center the event comes from, or null for workspace events and the test event
dataThe things the event is about. See What data contains

Each request also carries these headers:

HeaderValue
Content-Typeapplication/json
User-AgentND-Webhooks/1.0
X-ND-EventThe event name, the same as event in the body
X-ND-DeliveryThe ID of this delivery to this endpoint. It stays the same across retries
X-ND-SignatureThe signature that proves the request comes from Notiondesk. Checking it is covered in Verify that a webhook comes from Notiondesk

What data contains

data holds one or more objects, depending on the event:

EventWhat is in data
contact_message.createdcontact_message: id, name, email, subject, message, locale
article.created, article.updated, article.published, article.unpublished, changelog.publishedarticle: id, locale, title, slug, url, status
article.translatedarticle in the new language, and source_locale
article.deletedarticle: id
article.reaction.added, article.reaction.changed, article.reaction.removedarticle: id, and reaction: type
article.feedback.createdarticle: id, and feedback: id, name, email, message, locale
category.created, category.updatedcategory: id, locale, name, slug
category.deletedcategory: id
sync.completedsync: trigger, duration_seconds, pages_synced, pages_updated
sync.failedsync: reason, pages_processed
site.updated, site.createdsite: id, name, url
site.deletedsite: id
site.custom_code.updatedcustom_code: type (css or js)
site.domain.verified, site.domain.verification_faileddomain: name
integration.updatedintegration: type, enabled
notion.connected, notion.disconnected, notion.access_lostAn empty object, {}
chatbot.updatedchatbot: id, name, enabled
chatbot.guidance.created, chatbot.guidance.updatedguidance: id, type, title, enabled
chatbot.guidance.deletedguidance: id
redirect.created, redirect.updatedredirect: id, source_path, type, article_id, category_id
redirect.deletedredirect: id
workspace.updatedworkspace: id, name
workspace.join_request.created, .approved, .declinedjoin_request: id, email, status
team_member.invited, .joined, .role_changed, .status_changedteam_member: id, email, role, status
team_member.removedteam_member: id
team_member.logged_inuser: id, email, name
api_key.created, api_key.revokedapi_key: id, prefix, label, scopes, expires_at
api_key.rotatedapi_key for the new key, and previous_api_key: id
pingmessage

data never contains attachments, secrets, custom code or billing details.

Example data by event family

These examples show only data. The rest of the request is the same for every event.

Contact form, contact_message.created:

{
  "contact_message": {
    "id": "019a8f31-5c2e-7a41-8b9d-2e6f0a7c4b23",
    "name": "Jamie Rivera",
    "email": "[email protected]",
    "subject": "Invoice question",
    "message": "Hi, where can I download my latest invoice?",
    "locale": "en"
  }
}

Articles, article.translated:

{
  "article": {
    "id": "1763391842",
    "locale": "fr",
    "title": "Réinitialiser votre mot de passe",
    "slug": "reinitialiser-votre-mot-de-passe",
    "url": "https://help.acme-support.com/fr/articles/reinitialiser-votre-mot-de-passe",
    "status": "published"
  },
  "source_locale": "en"
}

status is the status of that language: draft, review, published, archived or translation source. url can be null if the help center has no address yet.

Reactions and feedback, article.feedback.created:

{
  "article": { "id": "1763391842" },
  "feedback": {
    "id": "019a8f33-8d4f-7b52-a1c3-6e9b2d0f7a35",
    "name": "Sam Lee",
    "email": "[email protected]",
    "message": "The screenshots don't match the new settings page.",
    "locale": "en"
  }
}

For reactions, reaction.type is smiley, neutral_face or disappointed. Help centers that show thumbs buttons send smiley for Yes and disappointed for No. On feedback, article.id is null when the article no longer exists.

Categories, category.created:

{
  "category": {
    "id": "1763392017",
    "locale": "en",
    "name": "Billing",
    "slug": "billing"
  }
}

Syncs, sync.completed and sync.failed:

{
  "sync": {
    "trigger": "automatic",
    "duration_seconds": 42,
    "pages_synced": 120,
    "pages_updated": 3
  }
}
{
  "sync": {
    "reason": "pages_failed",
    "pages_processed": 118
  }
}

trigger is manual, api or automatic. reason is pages_failed when some pages could not be synced, or failed when the sync stopped.

Help center settings, redirect.created:

{
  "redirect": {
    "id": "019a8f35-2a6c-7d63-b4e8-0c1f5a9d3e47",
    "source_path": "/old-help/reset-password",
    "type": "article",
    "article_id": "1763391842",
    "category_id": null
  }
}

Workspace and teammates, team_member.role_changed:

{
  "team_member": {
    "id": "019a8f37-7e1b-7f74-8c2d-9a4e6b1f0c59",
    "email": "[email protected]",
    "role": "editor",
    "status": "enabled"
  }
}

role is admin, editor, billing_manager or viewer. status is enabled, disabled or pending_invite.

API keys, api_key.rotated:

{
  "api_key": {
    "id": "019a8f39-3f8a-7185-9d6e-1b7c4e2a8d6b",
    "prefix": "nd_wsk_4fa9c2e17b30",
    "label": "CRM sync",
    "scopes": ["read"],
    "expires_at": null
  },
  "previous_api_key": { "id": "0199c4d2-6b3e-7296-ae0f-5d8a1c7e9b7d" }
}

Test event, ping:

{
  "message": "Test event from Notiondesk."
}

Handle events in your receiver

  • Respond quickly. Return any 2xx status code first, then do the work. Notiondesk waits 5 seconds for your server to start answering and 10 seconds in total, and only reads the status code.
  • Expect duplicates. The same event can arrive more than once, for example after a retry. Skip any id you already processed.
  • Don't rely on order. Events can arrive out of order. Use occurred_at when order matters.
  • Read data as the latest state. data is read when the event is sent, so two quick changes to an article can both carry the later version. If the item is gone by then, the event is skipped.

Common questions

Do I get the full article content?

No. Article events carry the title, slug, URL and status. Use the Notiondesk API if you need more.

How do I tell which help center an event comes from?

Read site_id. It is the ID of the help center, or null for workspace events and the test event.

Why didn't I get an event for every reaction?

Reactions and article feedback are capped at 120 events per minute for each help center. Events over the cap are not sent. Use your help center analytics for totals.

Can I receive the same event twice?

Yes, for example after a retry. The id stays the same, so ignore one you have already processed.

What does version mean?

It tells you which request format was used. Requests currently use 2026-11-06.

Related articles

Was this page helpful?

Still need help? Ask us