Docs
/
/
Contact supportLog inGet started
Platform
Integrations
In-app UI
API reference
CLI reference
Management API
Developer tools
Agents
Tutorials
Developer tools
Outbound webhooks
Event types

Webhook event types

Learn more about the types of events that Knock sends webhook events for.

Messages

#

Occurs when a message is successfully sent to a channel provider.

dataMessage

The associated message.

Occurs when a message is marked as delivered to the user by the provider. Not all channels support delivery tracking. Reference the docs on the delivered message status to see which channels and providers are supported.

dataMessage

The associated message.

Occurs when a message delivery attempt fails and may be retried.

dataMessage

The associated message.

event_dataEventData

Additional information about the attempt, the total attempts, and whether or not it will be retried.

attemptnumber

The current attempt count.

max_attemptsnumber

The total number of attempts that can be tried.

retryableboolean

Whether or not the current attempt is retryable. This field may be absent if retryability is not determined.

Occurs when a message delivery attempt fails permanently. Delivery will not be retried.

dataMessage

The associated message.

event_dataEventData

May include additional information about the failure.

failure_reasonstring

The reason for a message failure. One of fatal_error or retries_exhausted.

failure_detailsstring

Details about a message failure. This field varies by provider and is nullable.

Occurs when a message delivery attempt fails due to bounce or a delivery status check results in a bounce because of a bad recipient(s) identifier. Delivery will not be retried.

dataMessage

The associated message.

event_dataEventData

May include additional information about the failure.

failure_reasonstring

The reason for a message failure.

failure_detailsstring

Details about a message bounce.

tokenstring

The erroneous token causing the bounce. Only applicable for push messages.

Occurs when a recipient reports a delivered email as spam and the email provider relays the complaint to Knock. A complaint is a post-delivery event, so it does not change the message's delivery status. Only available on select email providers with delivery status webhooks configured to send complaint events: Postmark, Resend, AWS SES, SendGrid, and Mailgun.

dataMessage

The associated message.

event_dataEventData

Includes a subset of the provider's complaint payload, such as the complained recipient address and the provider's complaint timestamp. The available fields vary by provider.

Occurs when a message is seen by its recipient.

dataMessage

The associated message.

Occurs when a message is unseen by its recipient.

dataMessage

The associated message.

Occurs when a message is read by its recipient.

dataMessage

The associated message.

Occurs when a message is unread by its recipient.

dataMessage

The associated message.

Occurs when a message is archived by its recipient.

dataMessage

The associated message.

Occurs when a message is unarchived by its recipient.

dataMessage

The associated message.

Occurs when a message is interacted with by its recipient. For the Knock in-app feed, this indicates that your recipient has explicitly clicked on the notification cell in their feed.

dataMessage

The associated message.

event_dataEventData

Includes any additional metadata included in the interacted event.

Workflow runs

#

A workflow recipient run represents the execution of a workflow for a single recipient. Use these events to respond when a recipient's workflow run starts, completes, or encounters an error. You can also inspect runs via the workflow recipient runs API.

Occurs when a workflow recipient run begins execution.

dataWorkflowRecipientRun

The associated workflow recipient run.

Occurs when a workflow recipient run completes.

dataWorkflowRecipientRun

The associated workflow recipient run.

Occurs when an error is encountered during a workflow recipient run.

dataWorkflowRecipientRun

The associated workflow recipient run.

Commits

#

With environments enabled, promoting commits copies them from one environment into another, and merging a branch promotes its commits into the development environment. Use these events to respond when changes land in an environment. You can also inspect promotes via the list commits endpoint. Publishing a change creates a commit, and Knock sends a *.committed event for that commit.

Occurs whenever commits are promoted into an environment, including when a branch is merged. Knock sends one event per promote to webhooks in the destination environment. Promoted commits don't send *.committed events. Learn more about reacting to promotes.

dataPromoteGroup

The associated promote group. Use its id to list the commits the promote created.

Branches

#

Branches are available once you've enabled environments. Knock sends branch events to webhooks in the branch's parent environment (i.e. development). Merging a branch sends commits.promoted with a source_type of branch, not a separate merge event.

Occurs whenever a branch is created.

dataBranchEventData

The associated branch and the user who created it.

branchobject

The branch's slug, name, parent_environment, and created_at.

actorobject | null

The name and email of the user who created the branch. Null when no user is associated with the event.

Occurs whenever a branch is deleted.

dataBranchEventData

The associated branch and the user who deleted it.

branchobject

The branch's slug, name, parent_environment, created_at, and deleted_at.

actorobject | null

The name and email of the user who deleted the branch. Null when no user is associated with the event.

Occurs whenever a branch is rebased onto its parent environment.

dataBranchEventData

The associated branch and the user who rebased it.

branchobject

The branch's slug, name, parent_environment, created_at, and rebased_at.

actorobject | null

The name and email of the user who rebased the branch. Null when no user is associated with the event.

Resources

#

Knock sends a *.updated event when a resource changes in an environment and a *.committed event when that change is committed. Committed events include the commit ID in event_data. Goals publish on save, so they send only goal.updated, which carries the commit ID.

Audiences

#

Knock sends these events for user-visible audiences and skips managed and system audiences.

Occurs whenever an audience is updated in the environment.

dataAudience

The associated audience.

Occurs whenever an audience is committed to the environment.

dataAudience

The associated audience.

event_dataEventData

Additional information about the commit.

commit_idstring

The ID of the corresponding commit for the event.

Email layouts

#

Occurs whenever an email layout is updated in the environment.

dataEmailLayout

The associated email layout.

Occurs whenever an email layout is committed to the environment.

dataEmailLayout

The associated email layout.

event_dataEventData

Additional information about the commit.

commit_idstring

The ID of the corresponding commit for the event.

Goals

#

Occurs whenever a goal is updated in the environment. Goals publish on save, so this event carries the commit ID.

dataGoal

The associated goal.

event_dataEventData

Additional information about the commit.

commit_idstring

The ID of the corresponding commit for the event.

Guides

#

Occurs whenever the content, status, or activation schedule of a guide changes in the environment.

dataGuide

The associated guide.

Occurs whenever a guide is committed to the environment.

dataGuide

The associated guide.

event_dataEventData

Additional information about the commit.

commit_idstring

The ID of the corresponding commit for the event.

Message types

#

Occurs whenever a message type is updated in the environment.

dataMessageType

The associated message type.

Occurs whenever a message type is committed to the environment.

dataMessageType

The associated message type.

event_dataEventData

Additional information about the commit.

commit_idstring

The ID of the corresponding commit for the event.

Partials

#

Occurs whenever a partial is updated in the environment.

dataPartial

The associated partial.

Occurs whenever a partial is committed to the environment.

dataPartial

The associated partial.

event_dataEventData

Additional information about the commit.

commit_idstring

The ID of the corresponding commit for the event.

Reusable requests

#

Occurs whenever a reusable request is updated in the environment.

dataReusableRequest

The associated reusable request.

Occurs whenever a reusable request is committed to the environment.

dataReusableRequest

The associated reusable request.

event_dataEventData

Additional information about the commit.

commit_idstring

The ID of the corresponding commit for the event.

Translations

#

Occurs whenever a translation is updated in the environment.

dataTranslation

The associated translation.

Occurs whenever a translation is committed to the environment.

dataTranslation

The associated translation.

event_dataEventData

Additional information about the commit.

commit_idstring

The ID of the corresponding commit for the event.

Workflows

#

Occurs whenever a workflow is updated in the environment.

dataWorkflow

The associated workflow.

Occurs whenever a workflow is committed to the environment.

dataWorkflow

The associated workflow.

event_dataEventData

Additional information about the commit.

commit_idstring

The ID of the corresponding commit for the event.

New chat