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
httpsURL. 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 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" }'{ "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.
{
"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.
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:
| 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. |
{
"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
Check every delivery before you act on it:
- Read the raw request body, before any JSON parsing. The signature covers the exact bytes.
- Split the header into
tandv1. - Compute the HMAC-SHA256 of
<t>.<raw body>with the endpoint secret, as lowercase hex. - Compare it with
v1in constant time. - Refuse a
tmore than five minutes old, so an old delivery cannot be replayed.
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);
// });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 "", 2005. Answer fast, and expect retries
- Answer with any
2xxwithin 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.
Score a resume against a job post
Show a job seeker how well their resume matches a posting, which keywords it misses and what to fix. Then close the gap with one more call.
Read the candidate profile GET
The candidate's name, contact, location, work authorization and links: the facts GetMattered fills application forms with. Free.