With a webhook Beamcore automatically sends a message to an address of your choice as soon as something happens, for example when a project is created. That way you keep your own system up to date without retyping data yourself. The Beamcore interface is in Dutch, so button and menu names are shown in Dutch with a translation.
Note: the menu Integraties (Integrations) is not switched on by default. It is a setting per company that Beamcore enables for you on request. If you do not see the menu, contact Beamcore. In addition, the menu is only visible to an owner of the company.
Creating a webhook
- Go to Integraties → Webhooks (Integrations → Webhooks) and create a new webhook.
- Fill in a Naam (Name) by which you recognise the connection.
- At URL, fill in the address where your system receives the messages.
- Under Events, tick what you want to receive a message about. You must choose at least one.
- Leave Actief (Active) switched on and save.
A webhook that is not active does not receive messages. Via Bewerken (Edit) you change the name, URL and events later.
The available events
Beamcore sends messages for these events:
- Project aangemaakt (Project created, project.created): a new project has been created. The message contains the id and the name of the project.
- Project gearchiveerd (Project archived, project.archived): a project gets the status archived. The message contains the id, the name and the previous status.
- Tekening geüpload (Drawing uploaded, drawing.uploaded): a new drawing has been added to a project. The message contains the id and the name of the drawing and the id of the project.
- Test-bericht (Test message, webhook.test): the message that the button Stuur test (Send test) sends.
What a message looks like
Beamcore sends each message as a POST request with a JSON body to your URL. The body always has three fields:
- event: the name of the event, for example project.created.
- occurred_at: the time in ISO 8601 notation.
- data: the data that belongs to the event.
With each request Beamcore sends these headers:
- Content-Type: application/json.
- X-Beamcore-Event: the name of the event.
- X-Beamcore-Signature: the signature of the message.
Your system must respond with a status code in the 200 range. Any other response counts as failed. Beamcore waits a maximum of 30 seconds for a response.
Verifying the signature
Each webhook automatically gets its own secret key when it is created. The header X-Beamcore-Signature contains the text sha256=, followed by the HMAC-SHA256 of the raw body of the message, calculated with that key. Calculate the same value on your side over the received body and compare it with the header. If they match, you know that the message comes from Beamcore and was not changed on the way.
The secret key is currently not visible in the portal. If you want to verify the signature, contact Beamcore.
Sending a test message
- In the list, click Stuur test next to the webhook and confirm.
- Beamcore queues a test message for the URL of that webhook.
- Open Integraties → Webhook log (Integrations → Webhook log) to see whether the message has arrived.
You do not need to tick the event Test-bericht for this. If you get the message that nothing has been queued, check whether the webhook is active.
Failed messages
If delivery fails, Beamcore tries again, up to a maximum of five attempts per message. Between the attempts there is an increasing waiting time: 10 seconds, 30 seconds, 2 minutes and 10 minutes. In the list of webhooks you see Laatste succes (Last success) and Laatste fout (Last error) per webhook.
The webhook log
Under Integraties → Webhook log you find every delivery attempt, with the newest at the top. Per attempt you see:
- Webhook and Event: which connection and which event.
- Status: the status code your system returned.
- Ok?: whether the delivery succeeded.
- Poging (Attempt): which attempt this was.
- Duur (ms) (Duration in ms): how long your system took to respond.
- Fout (Error): the reason if it failed, for example a status code or a timeout.
- Tijdstip (Time): when the attempt took place.
The tiles above the table show the total number of attempts and how many succeeded and failed in the last 24 hours.