# MatterFirst sample integration

A small, complete integration against the MatterFirst REST API and webhooks.
It:

1. checks who the API key acts for (`GET /api/v1/me`);
2. lists every open matter, following `links.next` page by page;
3. creates a matter with an `Idempotency-Key`, so a retried request replays the
   first answer instead of creating a second matter;
4. waits for `Retry-After` on a 429 and retries 5xx answers with a growing wait,
   keeping the same `Idempotency-Key`;
5. registers a webhook address and verifies each delivery's
   `x-matterfirst-signature` and `x-matterfirst-timestamp` before trusting it.

## Run it

```
MATTERFIRST_URL=https://matterfirst.com \
MATTERFIRST_API_KEY=mf_live_… \
elixir run.exs
```

The key needs `matters:read`, `matters:write`, `matter_types:read`,
`webhooks:read` and `webhooks:write`. Set `MATTERFIRST_WEBHOOK_URL` to an https
address you control to register it for `matter.created`.

You need Elixir 1.15 or later; `run.exs` fetches its two libraries (Req and
Jason) the first time it runs.

## Kept honest

MatterFirst's own test suite loads `matterfirst_sample.exs` and runs it against
the real API on every build: listing, creating twice with one key, a missing
scope, retrying a 429, receiving and verifying a real signed delivery, refusing
a tampered or stale one, and the firm switching API keys and outgoing updates
off.

The full guide is at https://matterfirst.com/docs/developers.