Webhooks
procuris reports new tenders and hits to your system on its own. When webhooks fit better than the API and how your IT receives the first message.
You receive this service through an individual quote.
Webhooks report events without your system asking. A webhook is a message that procuris sends on its own to a web address of your system as soon as a chosen event occurs. For the chosen events, regular polling is no longer needed. Your CRM can, for example, create a new hit as a sales opportunity without anyone copying it from procuris. Webhooks do not deliver the data from before the setup, however. The API fetches that. Both carry the same record.
Individual quote
You get webhooks through an individual quote. You request them through the contact block at the bottom of this page, or in procuris under Settings › Organization in the On request section with Webhooks. The path from the request to the set-up access, and who builds the integration, is described in Integrations. After the setup, the person with the role Owner manages the webhooks themselves.
Which events exist
Six events cover tenders, hits and the test:
- New tender that matches your filters (
tender.published) - Changed tender, for example a new contract value or new lots (
tender.updated) - Postponed deadline (
tender.deadline_changed) - Tender ended: expired, cancelled, awarded or merged with another record (
tender.archived) - New hit of a saved search with its Fit from 0 to 100 (
search.hit). A saved search is a stored search that keeps running every morning. - Test message that you trigger in procuris (
webhook.test)
Tender events arrive up to one hour after procuris has taken over the change. The reference point is the time at which procuris took over the change (lastModified), not the change at the contracting authority. Hits arrive once in the morning with the run of the saved search. Details and examples are under Events.
Webhook or API?
Webhooks fit when your system is reachable and should react. The API fits when your system fetches on its own schedule or needs the existing data.
| Situation | Way |
|---|---|
| Your system should react without a schedule of its own, for example pass new hits to a team | Webhook |
| Your system cannot be reached from outside, for example behind a firewall without incoming connections | API, your system fetches every hour |
| Initial load, meaning the one-time transfer of the existing data | API, because webhooks only report what happens from the setup of the access onward |
| Nightly load into the BI tool | API |
| Keep all tenders matching your filters in the CRM (variant A) | both: API for the initial load and the nightly sync, webhooks for changes |
| Keep only the hits of your saved searches in the CRM (variant B) | webhooks only, with search.hit, tender.updated and tender.archived, without an initial load |
Variant B needs no API, but it starts empty. The first hits arrive on the morning after the setup. CRM and ERP describes both variants step by step.
What your IT provides
Your IT provides three things:
- an HTTPS address that is reachable from the internet and accepts
POSTrequests - the signature check, with ready-made libraries for Python, JavaScript, Java, Go and C#, among others, see Delivery and security
- a response with status 2xx within 15 seconds
For short flows such as a Teams message, a workflow builder is enough. For a CRM, you build a receiver of your own instead of using a builder, because the sync must detect duplicate messages and skip older states, see CRM and ERP.
Receive your first message
Only the role Owner can enter settings in procuris. The owner sets up webhooks under Settings › Organization › Webhooks. The section appears only once access has been set up after the contract is signed. Until then, the Webhooks row in the On request section of the same page only requests a quote. Your IT builds the receiver and determines the values, while the owner enters them in procuris. If the IT lead has the role Owner, they do both.
Provide an HTTPS address. procuris sends only to HTTPS addresses, including the test message. For a first try on a computer without a web address of its own, a tunnel service that forwards an HTTPS address to your computer is enough. For production, use a fixed address of your system or of a workflow builder instead of the tunnel, because the tunnel address is reachable only while your computer is running.
Create an endpoint. The owner creates an endpoint under Webhooks and enters your address. There, they choose the events, the filters and the saved searches, see Events. They can change the address and the selection later or delete the endpoint.
Pass on the secret. procuris creates a signing secret of its own for each new endpoint. The owner passes it to your IT through a password manager instead of email or chat, because messages there stay readable for a long time.
Set up the receiver. Your receiver accepts POST requests and checks the signature with one
of the ready-made libraries from Delivery and
security. It stores the message and responds with
204 within 15 seconds. It responds to a message with an invalid signature with 401 and discards
it.
Send a test message. Under Webhooks, Send test message sends a message of type
webhook.test to the endpoint. It carries the sample record under data.tender and data.test
set to true. procuris shows the response of your receiver next to it. If it shows a status
2xx, the receiver is ready.
Process real messages. From now on, the chosen events arrive. Events describes how the messages are structured.
Manage it yourself in operation
The owner changes webhooks without going through support. Under Webhooks, they can do the following:
- create, change and delete endpoints, and choose events, filters and saved searches per endpoint
- Renew secret for a planned rotation, with a 24-hour transition in which the old and the new secret are both valid
- Replace secret now, if a secret has become public. The old one is no longer valid from then on. Messages fail until your IT has entered the new one, and then arrive again according to the retry schedule.
- Send test message, for example after a change to your receiver
- Resume delivery after procuris has stopped it: after 5 days without a successful delivery or after your system responds with 410
- resend missed messages from the last 7 days. Only a system with API access can fill older gaps in tender events. Older hits cannot be recovered.
Delivery and security describes each of these in detail. If nobody with the role Owner can be reached, support@procuris.eu helps as the emergency route.
At a glance
| Property | Value |
|---|---|
| Standard | Standard Webhooks, an open specification with verification libraries for many languages |
| Transport | POST over HTTPS, content as JSON |
| Authenticity | HMAC-SHA256 in the headers webhook-id, webhook-timestamp, webhook-signature |
| Success | status 2xx within 15 seconds |
| Retry | up to nine more attempts over just over three days |
| Management | by the role Owner under Settings › Organization › Webhooks |
Request a quote
Tell us what you want to use or connect. Your quote is based on that scope.