# React to custom object events

Receive an event when a record is created, updated, or deleted, and use it to start a workflow or update your other systems.

Stripe creates an [event](https://docs.stripe.com/event-destinations/overview.md) when you create, update, or delete a record. Use events to start a workflow, notify another system, or sync data elsewhere.

## Event types

Each object definition has its own event types, named with the object’s singular API name:

```text
v2.extend.objects.<singular_name>.created
v2.extend.objects.<singular_name>.updated
v2.extend.objects.<singular_name>.deleted
```

For example, a shipment object has `v2.extend.objects.shipment.created`. The event type uses the singular name, even though API paths use the plural (`/v2/extend/objects/shipments`).

## Subscribe to events

To receive events at a [webhook endpoint](https://docs.stripe.com/webhooks.md) or in [Amazon EventBridge](https://docs.stripe.com/event-destinations/eventbridge.md), create an event destination with the API. List the event types you want in `enabled_events`:

The example reads your key from `STRIPE_SECRET_KEY`. If you use a restricted API key, give it **Write** access to **Webhook Endpoints, Event Destinations**. This permission is separate from **Object Records** access and allows subscribing to events across your account. Grant it only to the key that configures the destination, not to keys that only manage records.

```bash
curl https://api.stripe.com/v2/core/event_destinations \
  -H "Authorization: Bearer $STRIPE_SECRET_KEY" \
  -H "Stripe-Version: 2026-10-28.preview" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shipment updates",
    "type": "webhook_endpoint",
    "event_payload": "thin",
    "events_from": ["@self"],
    "enabled_events": ["v2.extend.objects.shipment.updated"],
    "webhook_endpoint": {"url": "https://example.com/webhooks"},
    "include": ["webhook_endpoint.signing_secret"]
  }'
```

The response includes `webhook_endpoint.signing_secret`. Store it securely, because you use it to [verify that events come from Stripe](https://docs.stripe.com/webhooks.md#verify-events), and you can’t retrieve it again with the API. During private preview, you can’t choose custom object event types in [Workbench](https://docs.stripe.com/workbench.md), and you can’t receive custom object events from other accounts. To start a workflow from a custom object event, see [Use custom objects with Stripe Apps and Workflows](https://docs.stripe.com/custom-objects/apps-and-workflows.md).

## The event payload

Custom object events are [thin events](https://docs.stripe.com/events/how-events-work.md#thin-events). The payload tells you which record changed, but doesn’t include the record’s fields or what changed.

```json
{
  "id": "evt_test_61RfVn0yAJiQAQHk7O16UQupaQVSQsnLcmkMmyS57EvT",
  "object": "v2.core.event",
  "type": "v2.extend.objects.shipment.updated",
  "created": "2026-10-30T12:00:00.000Z",
  "livemode": false,
  "context": null,
  "reason": {
    "type": "request",
    "request": {"id": "req_v2abc123", "idempotency_key": "a1b2c3d4"}
  },
  "related_object": {
    "id": "objrec_test_61RfVn0yAJiQAQHk7O16UQupaQVSQsnLcmkMmyS57ShP",
    "type": "v2.extend.objects.shipment",
    "url": "/v2/extend/objects/shipments/objrec_test_61RfVn0yAJiQAQHk7O16UQupaQVSQsnLcmkMmyS57ShP"
  }
}
```

To get the record’s current state, retrieve it from `related_object.url`, with the `Stripe-Custom-Object-Versions` header for the version you want. Because you choose the version when you retrieve the record, events keep working as your schema changes (see [Version your custom objects](https://docs.stripe.com/custom-objects/versioning.md)). You can also [retrieve an event](https://docs.stripe.com/api/v2/core/events/retrieve.md) with `GET /v2/core/events/:id`, and [list the events](https://docs.stripe.com/api/v2/core/events/list.md) for a record with `GET /v2/core/events?object_id=<record_id>`.

## Deleted records

Deleting a record removes it immediately, so retrieving it after a deleted event returns a `not_found` error. If other systems or workflows process a record’s events, delete the record only after they finish.