Meisei

    Reading the event log

    This guide is for a developer who would rather ask Meisei what happened than wait to be told. Every event a webhook can carry is also written to an event log, whether or not any webhook subscribes to it, and kept for 30 days.

    Use it to:

    • Poll for changes on a schedule instead of running an endpoint that accepts webhooks.
    • Catch up after your endpoint was down, since a delivery that fails all its retries is not sent again.
    • Replay everything since a point in time, for example after fixing a bug in your handler.

    Reading forward from where you left off

    Store the id of the last event you processed. Ask for everything after it:

    curl "https://your-store.meisei.app/api/events?after=Xb3kQ9Lm" \
  -H "Authorization: Bearer sk_..."

    Events after that one come back oldest first, each carrying the same data a webhook delivers:

    {
  "data": [
    {
      "id": "Pq7rT2Vw",
      "name": "customer.created",
      "idempotencyKey": "9f2c9a56-6f6a-4b16-9b0e-9f2e1d6b7c31",
      "data": { "id": "k3Fq8Zb2", "email": "sam@example.com" },
      "previousAttributes": null,
      "createdAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "nextCursor": null
}

    While nextCursor is not null, pass it back as cursor (with the same after) for the next page. When it is null you are up to date. Store the last id you saw and start from it next time.

    The key needs the webhooks:read permission, the same one that reads webhook deliveries.

    Only the events you care about

    Narrow the list with a filter on name:

    curl -G "https://your-store.meisei.app/api/events" \
  -H "Authorization: Bearer sk_..." \
  --data-urlencode 'after=Xb3kQ9Lm' \
  --data-urlencode 'filter={"name":{"$in":["order.created","order.updated"]}}'

    Without after, the list comes newest first, which is handy for a quick look at what just happened. filter can also narrow by createdAt. The full parameter list is in the API reference.

    Using it alongside webhooks

    A webhook delivery carries the same id the log lists the event under, and the same idempotencyKey. If you receive webhooks and also poll the log to fill gaps, record either value once and skip any event you have already handled.

    If something isn't working

    • An event you expected is missing. Check its name in the list of events. Imports from a CSV file, and the history Meisei pulls in when you first connect a store, fire no events.
    • Your stored id is more than 30 days old. Those events have aged out. Read the records you need from the API directly, then start again from the newest event.
    • A 403 response. The key is missing webhooks:read. Edit it under Settings → API keys.

    Next steps