Webhooks
Automatic notices to your system when something happens on the platform: events, filters, personal data, delivery history and what to do when it fails.
A webhook tells your system when something happens on the platform. For example: a student completed a lesson, and Cademí sends a notice to your CRM. The webhook is the address on your system (or on Zapier, Make, n8n) that receives these notices. You set it all up in Settings → Webhooks. The format of each event, for whoever will program the receiver, is at https://cademi.dev/webhooks.
The idea in one minute
- An event is a fact Cademí records in the account: a student got access, passed an exam, completed a lesson.
- A webhook is an address subscribed to some events.
- A delivery is each notice Cademí sends to that address.
A webhook delivery has nothing to do with a sales delivery (Deliveries).
The most important rule: the webhook listens to access, not to the sale. A gateway sale is not an event. What reaches your system is the access the sale produced.
The screen has two tabs:
- Endpoints: the list of webhooks. Each row shows Event / scope, Endpoint and Status. The Status is Active or Inactive, and you switch it on the row itself. The Events and Status filters and the search by address narrow the list.
- History: the deliveries.
There are two webhook formats:
- Cademí v3, the current format. One webhook receives several events, each with its own filter, and every delivery is signed. It is what New webhook creates, and it is what this article explains.
- Legacy v2 and Legacy v1 (discontinued), the old format, with one event per webhook. It only serves a system that already receives this format. New legacy webhook creates one. For a new integration, use New webhook.
Creating a webhook
- Open Settings → Webhooks.
- Click New webhook.
- Under Where to send, paste the Endpoint: your system's address, starting with https://.
- If you want, fill in the Description. It helps you recognize the webhook in the list and is not sent.
- Under When to send, check the events.
- For events that accept a filter, fill in the Send only when block, which appears right below. Empty means "whenever it happens".
- Under What each delivery carries, choose the level of personal data (see below).
- Review the Summary, on the side.
- Click Create webhook.
- In the Signing secret window, copy and keep the secret.
The secret does not appear again. With it, your server confirms that each delivery came from Cademí.
To choose the events, the screen has two tabs:
- Student journey groups the most used moments.
- Sync (advanced) lists every platform event, by group, with the technical name. It is for whoever keeps another system always in step with Cademí.
Search event searches both tabs. Check all and Uncheck apply per group. View delivery example shows what reaches your address, with sample data.
The moments of the student journey
| Moment | Events |
|---|---|
| Sign-up | Student created, Student tags updated, Custom field updated |
| Access | Access granted, First access, Access suspended or reactivated, Access revoked, Access restored |
| Progress | Course started, Lesson completed, Progress milestone reached, Progress updated, Course completed |
| Exams | Exam completed, Exam attempt reopened |
| Certificates | Certificate issued, Certificate revoked |
| Terms | Term accepted |
| Points | Points credited, Points adjusted |
| Support | Ticket opened, Ticket replied, Ticket closed, Question asked, Question answered, Comment posted, Comment replied |
Attention: this is where most mistakes happen. Each event has its own moment:
- Sale: the student receives a delivery and fires Access granted. Refund, late payment and payment coming back fire Access suspended or reactivated.
- Course started is the first completed lesson, not the access granted. For a welcome, use Student created or First access.
- Exam completed fires on pass or fail. For only one of them, filter by Exam result.
- Reaching 100% does not issue a certificate. Certificate issued only happens when someone requests the certificate.
- The notice for a comment or a question does not carry the text the student wrote.
- An administrator who views the area as a test student generates none of these events.
The filters
| Filter | On the events for | What it does |
|---|---|---|
| Product | progress, exams, certificates, comments and questions | A single product, or Any product |
| Lesson and Exam | lesson completed, comments, questions and exams | They appear after you choose the product. You can check several |
| Exam result | Exam completed | Passed or failed, Passed only or Failed only |
| On reaching | Progress milestone reached | 50%, 75% or 90% |
| From | Progress updated | A minimum percentage. Once the student passes it, every following lesson fires again. For a one-time notice, prefer the milestone |
| Sign-up type | Student created | Paid sign-up or Free sign-up. Sign-up with Google and sign-up through import are neither. With either choice, they are left out |
| Offer | Access granted | Only the accesses from that delivery: the buyers of this offer |
| Tag added to the student | Student tags updated | Only when that tag is added. A tag the student already had, or that was only removed, does not fire |
| Custom field and Only when filled in | Custom field updated | One field. If you want, only when it stops being empty |
| Term | Term accepted | A specific term |
| Points for | Points credited | The reason for the points (lesson, milestone, exam, comment) |
How much personal data goes
The level applies to every event of the same webhook.
| Level | What arrives | Use it when |
|---|---|---|
| IDs only, no personal data (the default) | The codes of the student and of what happened, with no name or contact. Your system looks up the rest through the API | The receiver queries the student, or only needs to count |
| With personal data masked | The codes, plus name, email and phone partly hidden. It is still personal data | The tool needs a hint of who it is, without storing the real contact |
| Full, with personal data | The data as it is in the student's record | The system needs to write to, call or bill the student. And it can be trusted to store that data |
Only an administrator authorized to see student data can choose the full level. If the webhook includes tickets, they must also see support. Cademí checks each delivery against whoever created the webhook. If that person loses the authorization, deliveries go out masked until it comes back, and the screen warns you.
A webhook's page
Click the row to open the webhook. At the top are the status, View this webhook history, Send test and Generate new secret.
The health panel shows:
- the Last delivered;
- the Last 24 hours: delivered, failed and queued;
- the state of the Address: Receiving normally, Deliveries paused after repeated failures or Testing the address again.
Send test sends a sample of the chosen event to your address right away. The sample has fictitious data, is signed with the current secret and is marked as a test. You see the HTTP status, the Time and the Response. The test does not go into the history and does not count toward the webhook's health.
Generate new secret creates a new secret and shows it once. The previous one keeps signing for 24 hours. This way, you switch the secret in the receiver without downtime.
History
The History tab lists deliveries from the last 60 days, in four views: All, Success, Pending and Failed. Only Failed has a count, because it is the queue that calls for action. The Webhook filter narrows by destination.
Each row shows Sent at, Event, Code (the destination's response), Endpoint and Status. If there was more than one attempt, the row shows the number.
| Status | What it means |
|---|---|
| Queued | Waiting for the next send |
| Sending | Going out right away |
| Success | The destination received it and responded with success |
| Error | The destination refused in a way that retrying won't fix (address that doesn't exist or is blocked). It only goes out again by manual resend |
| Exhausted | The attempts ran out without success. It only goes out again by manual resend or when the webhook is reactivated |
| Cancelled | It will no longer be sent. The webhook was deactivated or deleted before it went out, or the system abandoned the address |
Click the row to open Delivery details. The window shows the destination's Response and the Payload sent. On failed deliveries, it has the Resend button. Resending puts the same delivery back in the queue. It does not create a new event.
When the destination fails
If the address does not accept a delivery, Cademí tries again on its own:
- The wait between attempts grows from 2 minutes up to 6 hours.
- Cademí tries about 10 times, or for 72 hours.
- If the destination asks to wait, or is unstable, the postponement does not use up an attempt.
- A definitive refusal is not retried.
The path of a delivery to its final status, with the retries and the returns to the queue:
Carregando diagrama…
With the webhook Inactive, the delivery waits in the queue and is not cancelled. Reactivate and resend only returns what ran out or was cancelled by the deactivation in the last 48 hours. A delivery cancelled because the webhook was deleted does not come back.
| Situation | What happens | How it comes back |
|---|---|---|
| You set the webhook to Inactive | Deliveries are held. Waiting is not a failure | Turn it back on and they go out |
| The address fails on several different deliveries within 24 hours | The system deactivates the webhook and cancels what was still waiting. It emails the administrators who manage webhooks | On the webhook's page, Reactivate or Reactivate and resend the last 48 hours |
| The address goes a long time without responding | Every webhook pointing to that address is deactivated. This also applies in other accounts that use it | Reactivate each one |
The list and the webhook's page show the reason for the deactivation. Saving the webhook does not reactivate it. Fix the address, if needed, and use Reactivate. Nothing older than 48 hours comes back on its own.
Good to know
The receiver must tolerate repeats.
Resends and reactivations deliver the same event again. If your system does not recognize the repeated event, a CRM creates two contacts and an email tool writes to the student twice.
Deleting cancels what was waiting.
Deleting a webhook cancels pending deliveries. Completed ones stay in the history. Support can recover the deleted webhook.
Changing the level doesn't rewrite the past.
A richer level applies to what happens afterwards. What was already prepared goes out as it was.
A webhook is not a history.
It can be paused and turned off. To look back or build a report, use the API's event list, not a webhook feeding a spreadsheet.
Diamond.
The stage messages of Diamond funnels are on the Diamond screens (Diamond Funnels), not here.
Old and new on the same system.
A legacy webhook and a v3 webhook pointed at the same tool announce the same moment twice, under two names.
Frequently asked questions
I want to notify my CRM on every purchase.
In the Access moment, check Access granted and Access suspended or reactivated. If it is a specific delivery, filter by Offer. The webhook listens to access, not to the sale.
The event happened and nothing arrived.
Open the History and look for the delivery:
- Queued: the platform will still try.
- Error or Exhausted: check the destination's Response, fix it and resend.
- No delivery: the event is not checked, or the filter excluded the case.
If the list shows the webhook deactivated, reactivate it.
My webhook was deactivated on its own.
The address failed on several deliveries in a row. Fix the destination and test it with Send test. Then click Reactivate and resend the last 48 hours to recover what was left behind.
I got the same notice twice.
A resend or a reactivation delivers the same event again. Your system must recognize the repeated event.
API keys
The credential another system uses to read and change your platform's data through the API: creating the key, permissions, the secret and revoking.
Custom code
Code blocks in the student area and on login: Google Analytics, Tag Manager, Pixel, Active Campaign, WhatsApp, Push Alert and your own CSS or JavaScript.