# Receive webhooks (/docs/guides/receive-webhooks)

Get a signed event when an application lands, stops, needs the account owner or waits for approval, and check the signature before you trust it.

A webhook endpoint is a URL on your server.
When an application changes state, GetMattered sends it a signed `POST` with the new state.
You do not have to poll `GET /developer/applications/{id}`.

## Before you start [#before-you-start]

- Create a key in the dashboard at [getmattered.com/dashboard/developers](https://getmattered.com/dashboard/developers). See [Authentication](/docs/authentication).
- Your endpoint must be a public `https` URL. GetMattered does not follow redirects.
- An account can have up to 5 endpoints. Webhook calls are free: they spend no tokens.

You can also add, test and delete endpoints in the dashboard, on the **Webhooks** tab of the Developers page.

## 1. Add an endpoint [#1-add-an-endpoint]

```bash title="curl"
curl https://api.getmattered.com/api/v1/developer/webhooks \
  -H "Authorization: Bearer $GETMATTERED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/getmattered" }'
```

```json title="POST /developer/webhooks request"
{ "url": "https://example.com/hooks/getmattered" }
```

The answer holds the signing secret.
This is the only time you see it: store it now, next to your API key.
Later lists show only its first characters, in `secretPrefix`.

```json title="POST /developer/webhooks 201 response"
{
  "success": true,
  "data": {
    "id": 7,
    "url": "https://example.com/hooks/getmattered",
    "secret": "whsec_3q2-7wAbCdEfGhIjKlMnOpQrStUvWxYz0123456789",
    "secretPrefix": "whsec_3q2-7w",
    "createdAt": "2026-11-19 17:00:00"
  },
  "meta": { "requestId": "...", "timestamp": "2026-11-19T17:00:00.000Z", "version": "v1" }
}
```

## 2. Send a test event [#2-send-a-test-event]

`POST /developer/webhooks/{id}/test` queues one `webhook.test` event to the endpoint.
It goes out within a minute, signed like every real event.

```ts title="TypeScript (fetch)"
const headers = {
  'Authorization': `Bearer ${process.env.GETMATTERED_API_KEY}`,
  'Content-Type': 'application/json',
};

const created = await fetch('https://api.getmattered.com/api/v1/developer/webhooks', {
  method: 'POST',
  headers,
  body: JSON.stringify({ url: 'https://example.com/hooks/getmattered' }),
});
const { data: endpoint } = await created.json();
// Store endpoint.secret now: no later answer shows it.
const endpointId = endpoint.id;

const test = await fetch(`https://api.getmattered.com/api/v1/developer/webhooks/${endpointId}/test`, {
  method: 'POST',
  headers,
});
const { data } = await test.json();
console.log(data.eventId, data.queued);
```

`GET /developer/webhooks/{id}/deliveries` shows the newest deliveries to the endpoint: the event, its status, the attempts so far and the last HTTP status your endpoint answered.

## 3. What a delivery looks like [#3-what-a-delivery-looks-like]

Every delivery is a `POST` with a JSON body and three headers:

| Header | What it holds |
| --- | --- |
| `GetMattered-Signature` | `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`, under the endpoint secret. |
| `GetMattered-Event-Id` | The event id, the same as `id` in the body. |
| `GetMattered-Event-Type` | The event type, the same as `type` in the body. |

```json title="Event body"
{
  "id": "evt_3f9c2a7d6b8e4f0a9c1d2e3f4a5b6c7d",
  "type": "application.landed",
  "createdAt": "2026-11-19T17:01:00.000Z",
  "data": {
    "application": {
      "id": 2481,
      "status": "landed",
      "company": "Acme",
      "jobTitle": "Senior Frontend Engineer",
      "postingUrl": "https://job-boards.greenhouse.io/acme/jobs/4012345",
      "landedEvidence": ["receipt"],
      "trackingUrl": "https://getmattered.com/dashboard/applications/2481"
    }
  }
}
```

| `type` | When it is sent |
| --- | --- |
| `application.landed` | The employer confirmed the application. |
| `application.not_landed` | The application stopped without the employer confirming it. |
| `application.needs_you` | The application waits on the account owner. |
| `application.held_for_review` | The application is ready and waits for approval. |
| `webhook.test` | You sent a test event. `data.application` is `null`. |

## 4. Verify the signature [#4-verify-the-signature]

Check every delivery before you act on it:

1. Read the raw request body, before any JSON parsing. The signature covers the exact bytes.
2. Split the header into `t` and `v1`.
3. Compute the HMAC-SHA256 of `<t>.<raw body>` with the endpoint secret, as lowercase hex.
4. Compare it with `v1` in constant time.
5. Refuse a `t` more than five minutes old, so an old delivery cannot be replayed.

```js title="JavaScript (Node.js)"
import { createHmac, timingSafeEqual } from 'node:crypto';

const TOLERANCE_SECONDS = 300;

export function verifyGetMatteredSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(part => part.split('=', 2)));
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp) || typeof parts.v1 !== 'string') {
    return false;
  }
  if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) {
    return false;
  }
  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  const given = Buffer.from(parts.v1, 'utf8');
  const wanted = Buffer.from(expected, 'utf8');
  return given.length === wanted.length && timingSafeEqual(given, wanted);
}

// Express: keep the raw body for this route.
// app.post('/hooks/getmattered', express.raw({ type: 'application/json' }), (req, res) => {
//   const ok = verifyGetMatteredSignature(req.body.toString('utf8'), req.get('GetMattered-Signature') ?? '', process.env.GETMATTERED_WEBHOOK_SECRET);
//   if (!ok) return res.sendStatus(400);
//   const event = JSON.parse(req.body.toString('utf8'));
//   res.sendStatus(200);
// });
```

```python title="Python"
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300

def verify_getmattered_signature(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    try:
        timestamp = int(parts["t"])
        given = parts["v1"]
    except (KeyError, ValueError):
        return False
    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False
    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(given, expected)

# Flask:
# @app.post("/hooks/getmattered")
# def getmattered_hook():
#     if not verify_getmattered_signature(request.get_data(), request.headers.get("GetMattered-Signature", ""), os.environ["GETMATTERED_WEBHOOK_SECRET"]):
#         abort(400)
#     event = request.get_json()
#     return "", 200
```

## 5. Answer fast, and expect retries [#5-answer-fast-and-expect-retries]

- Answer with any `2xx` within 10 seconds. Do the slow work after you answer.
- Any other answer, or no answer, is retried: after 1 minute, 5 minutes, 30 minutes, then 2, 5, 10 and 24 hours. After the last try the delivery is marked failed.
- A retry carries the same event id. Store the ids you handled and skip a repeat.
- Events can arrive out of order. When the order matters, read the application with `GET /developer/applications/{id}`.

See [Apply to a job by API](/docs/guides/apply-to-a-job) for what each application state means.