Webhooks
A webhook sends a short message to an address you choose when something happens in MarkBook. A school uses one to start an automation, for example to post in a chat when reports are published, or to refresh a data warehouse when a period is locked. You need the permission Developer: API keys and webhooks. This page is for the MarkBook administrator and school IT.
What a webhook sends
The message says what happened. It carries IDs, subject names, counts, statuses and times. It carries no student names, no marks and no comments. To get the substance, your system then reads it through the read API with an API key.
Events
| Event | When it is sent |
|---|---|
| A report card is published to its family | A report is published |
| A published report is withdrawn | A report is unpublished |
| A report passes its approval step | A report is approved |
| A marks spreadsheet is imported into a markbook | A marks import finishes |
| A reporting period is locked — its marks are final | A period is locked |
| A locked period is reopened | A period is unlocked |
You choose which events each webhook receives under Send when.
Add a webhook
- Open Configuration → Developer and choose the tab Webhooks.
- Press Add webhook.
- Enter a Name, for example "n8n — report publishing".
- Enter the URL. It must use HTTPS and a public host. MarkBook refuses internal addresses, because it posts to this address on its own.
- Under Send when, tick the events.
- Save.
MarkBook then shows the signing secret. Copy it. It is shown once, and MarkBook keeps only a hash of it.
Each webhook is Active or Paused. Pause one to stop messages without deleting it. The list also shows each webhook's events and Last delivery.
Press Send test to send a test message and see your system receive it.
Check the signature
Every message carries headers so your system can trust it:
| Header | Meaning |
|---|---|
X-KP-Markbook-Signature | sha256= followed by an HMAC-SHA256 of the raw body, made with your signing secret |
X-KP-Markbook-Event | The event name |
X-KP-Markbook-Delivery | The attempt number |
Your system should compute the HMAC over the raw body with the secret, compare it with the header, and ignore any message that does not match.
Replies and failures
- Your system should answer quickly. MarkBook waits 10 seconds for the whole exchange. If your handler needs longer, accept the message and do the work in a queue on your side.
- A success is any normal "OK" reply. MarkBook does not store the body of your reply.
- A failure never stops the action in MarkBook. A report still publishes if your automation is down.
- Failures show in the tab Failed deliveries: When, Webhook, Event and Outcome (for example "No response"). Press Retry to send it again, or Dismiss to clear it.
INFO
A failing webhook is easy to miss: your automation looks healthy, and the event simply never arrived. Look at Failed deliveries after any outage on your side.
Good practice
- Treat the message as a signal, then read the details with the API.
- Check the signature every time.
- Make your handler safe to run twice, because you may retry a delivery.
- Use one webhook per purpose, with a clear name.