Overview - Marty for Developers

Marty webhooks allow your application to receive real-time notifications when specific events occur. Instead of repeatedly polling the API for changes, you can subscribe to events and let Marty notify your system automatically. Webhooks can be used to:

Trigger workflows in your application
Synchronize data with external systems
Send events to third-party services
Build real-time integrations

Subscriptions

A webhook subscription defines which events you want to receive and where Marty should deliver them. Each subscription includes:

One or more topics
A destination
The workspace the subscription belongs to

Topics

A topic represents an event that can trigger a webhook notification. When creating a subscription, select the topics your integration needs to receive. Marty currently supports the following webhook topics.

Assessment orders

assessment-order.created — Triggered when a new assessment order is created.
assessment-order.completed — Triggered when an assessment order is completed.
assessment-order.result-updated — Triggered when the result of an assessment order is updated.

Assessments

assessment.created — Triggered when a new assessment is created.
assessment.updated — Triggered when an existing assessment is updated.
assessment.deleted — Triggered when an assessment is deleted.

Candidate evaluations

candidate-evaluation.completed — Triggered when a candidate evaluation is completed.

Candidates

candidate.created — Triggered when a new candidate is created.
candidate.updated — Triggered when an existing candidate is updated.
candidate.deleted — Triggered when a candidate is deleted.
candidate.anonymized — Triggered when candidate data is anonymized.

Organizations

organization.updated — Triggered when organization information is updated.

Compliance

compliance.updated — Triggered when compliance-related information is updated.

Candidate surveys

candidate-survey.created — Triggered when a new candidate survey is created.
candidate-survey.updated — Triggered when an existing candidate survey is updated.
candidate-survey.invitation-sent — Triggered when a candidate survey invitation is sent.
candidate-survey.response-received — Triggered when a candidate survey response is received.

Connected accounts

connected-account.created — Triggered when a new connected account is created.
connected-account.updated — Triggered when an existing connected account is updated.
connected-account.deleted — Triggered when a connected account is deleted.

Notifications

A webhook notification is the object Marty sends when an event matching one of your subscribed topics occurs. Each notification contains information about:

Which event occurred
When the event occurred
The resource associated with the event
Delivery information that can help with processing and troubleshooting

The exact contents of the notification payload may vary depending on the topic, but notifications follow a common structure. A webhook notification can contain the following fields:

Field	Type	Description
`type`	`string`	The type of webhook object.
`id`	`string`	Unique identifier of the webhook notification.
`createdAt`	`timestamp`	The time when the notification was created.
`topic`	`string`	The topic that triggered the notification, for example `candidate.created`.
`deliveryAttempts`	`number`	Number of delivery attempts made for this notification.
`firstSentAt`	`timestamp`	The time when delivery was first attempted.
`data`	`object`	Container for the event-specific data.
`data.item`	`object`	The resource associated with the event. Its structure depends on the topic.

{
  "type": "notification_event",
  "id": "8d9b6d0f-3ef5-4f88-9fcb-2f15f62c46bb",
  "createdAt": "2026-08-26T14:32:10.123Z",
  "topic": "candidate.created",
  "deliveryAttempts": 1,
  "firstSentAt": "2026-08-26T14:32:10.123Z",
  "data": {
    "item": {
      "id": "44f48ec0-f5ed-45fa-883b-a347f75c90c4"
    }
  }
}

The topic field identifies the event that triggered the notification, while data.item contains the resource related to that event. For example, a candidate.created notification contains candidate-related data in data.item, while an assessment.updated notification contains assessment-related data. The structure of data.item therefore depends on the webhook topic.

Destinations

A destination defines where Marty sends webhook events. Supported destinations may include:

Webhook (HTTP endpoint)
Hookdeck Event Gateway
AWS SQS
AWS Kinesis
AWS S3
GCP Pub/Sub
Azure Service Bus
RabbitMQ
Apache Kafka

Choose the destination that best fits your integration architecture.

Webhook delivery

When an event occurs, Marty:

Finds active subscriptions for the event topic.
Sends the event to the configured destination.
Expects the destination to confirm successful receipt.

For HTTP webhook destinations, your endpoint should return a 2xx HTTP status code. If delivery fails, Marty retries the event using exponential backoff. The retry interval starts at 60 seconds and doubles after each failed attempt: 1 min → 2 min → 4 min → 8 min → 16 min → 32 min → 1 h 4 min → 2 h 8 min → 4 h 16 min Persistent delivery failures may cause the destination to be temporarily disabled.

Duplicate events

Webhook events may occasionally be delivered more than once. Your integration should process webhook events idempotently so that receiving the same event multiple times does not cause duplicate actions.

Delivery order

Webhook events are not guaranteed to arrive in the order in which they occurred. Use the event timestamp when the processing order is important.

Best practices

To ensure reliable webhook processing:

Respond with a 2xx status code as quickly as possible.
Process long-running tasks asynchronously.
Handle duplicate events safely.
Design your integration to tolerate retries.
Use event timestamps when ordering matters.
Verify webhook authenticity when signature verification is available.

​Subscriptions

​Topics

​Notifications

​Destinations

​Webhook delivery

​Duplicate events

​Delivery order

​Best practices