Skip to Content

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

  • Create a key in the dashboard at getmattered.com/dashboard/developers. See 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

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" }'
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.

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

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

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

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

HeaderWhat it holds
GetMattered-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, under the endpoint secret.
GetMattered-Event-IdThe event id, the same as id in the body.
GetMattered-Event-TypeThe event type, the same as type in the body.
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"
    }
  }
}
typeWhen it is sent
application.landedThe employer confirmed the application.
application.not_landedThe application stopped without the employer confirming it.
application.needs_youThe application waits on the account owner.
application.held_for_reviewThe application is ready and waits for approval.
webhook.testYou sent a test event. data.application is null.

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.
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
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

  • 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 for what each application state means.

On this page