Consuming events

Robaws offers 2 ways to their api consumers to capture events of what happened in the Robaws domains.

Supported event types

Currently, the following event types are supported. If you need an other event, please let us know via support@robaws.be.
These events are supported by both PUSH and PULL consumers.

clients:ClientUpdated
clients:ClientCreated
projects:ProjectUpdated
projects:ProjectCreated
planningItems:PlanningItemUpdated
planningItems:PlanningItemCreated
salesInvoices:SalesInvoiceCreated
salesInvoices:SalesInvoiceUpdated
salesInvoices:SendSalesInvoiceToAccountantRequested
purchaseInvoices:PurchaseInvoiceCreated
purchaseInvoices:PurchaseInvoiceUpdated
purchaseInvoices:SendPurchaseInvoiceToAccountantRequested
articles:ArticleCreated
articles:ArticleUpdated
articles:StockChanged
offers:OfferCreated
offers:OfferUpdated

Using PUSH consumers aka webhooks (preferred method)

To start using webhooks with Robaws, create an event consumer by doing a POST on /api/v2/event-consumers.
To create a PUSH consumer, you should specify an url. For the full request definition see the api reference docs.
After a minute, when your subscription becomes active, you should receive HTTP POST calls from us to the URL you specified when you were creating the event consumer.

POST https://your-host/your-webhook-endpoint
Content-Type: application/json
X-Robaws-Webhook-Secret: secret-returned-on-subscription-creation
X-Robaws-Webhook-Invocation: unique-id-of-this-webhook-message
{
    "context":"planningItems",
    "type":"PlanningItemUpdated",
    "timestamp": 1646387645,
    "payload": {
        "id": "7895"
    }
}


- Webhook payloads only contain the id of the concerning resource. This is for security reasons.
- You should use our api to fetch the latest data of the specific resource.
- We consider the webhook successful when the endpoint returns an 2XX response. We will retry several times as long as your endpoint fails to response successfully. Our connection timeout is 10 seconds and read timeout is 10 seconds
- Webhooks can be tested easily using https://webhook.site

Using PULL consumers (only allowed when you are technically not in the possibility to host a webhook URL)

To start receiving events from Robaws, create an event consumer by doing a POST on /api/v2/event-consumers.
To create a PULL consumer, you should not specify an url. For the full request definition see the api reference docs.
For PULL consumers, the following extra endpoints are available:

GET /api/v2/event-consumers/{consumerId}/messages
Return you the next available messages (max 10 per request)
POST /api/v2/event-consumers/{consumerId}/delete-message
Request you should execute after each message you processed successfully.
For the full request definitions see the api reference docs..

Preferably, when you start reading from the /messages endpoint, you should continue reading until it does not return any message anymore. You can decide to start reading once a day for example. Then you will have much more messages to process than when you start reading multiple times a day.

Important
Events are only retained for 7 days. If you do not call the /messages endpoint for 7 days, you consumer will be deleted. You will need to create a new consumer then, and messages will only be collected starting from then.
Was dit artikel nuttig?
Annuleer
Dankuwel!