Webhooks

Tripletex WebHook’s supports a growing number of internal events for your integrations to subscribe to.

You can see the API2 endpoints for managing your WebHook subscriptions under /event and /event/subscription in the swagger doc.

List currently available events

The list of events you can subscribe to is currently limited to a select few, but we are very happy to expand based on use-cases. Let us know if you have any suggestions!

To get the list of supported events from the API, make a request to GET https://tripletex.no/v2/event:

curl -X GET --header 'Accept: application/json' --header 'Authorization: Basic ' 'https://tripletex.no/v2/event'

The following events are available as of the time of writing:

Event	Description
invoice.charged	A new invoice has been created and charged.
supplier.create/update/delete	A supplier has been created/updated/deleted.
employee.create/update/delete	An employee has been created/updated/deleted
order.create/update/delete	An order has been created/updated/deleted.
product.create/update/delete	A product has been created/updated/deleted.
account.create/update/delete	A booking account has been created/updated/deleted.
project.create/update/delete	A project has been created/updated/deleted.
customer.create/update/delete	A customer has been created/updated/deleted.
contact.create/update/delete	A contact has been created/updated/deleted.
archiverelation.create/update/delete	An document archiverelation has been created/updated/deleted. Read more here.
notification.sent	A notification has been sent to the employee (owner of token)
voucher.create/update/delete	A voucher has been created/updated/deleted.
voucherstatus.ready	A new voucher is ready to be processed from the voucher reception.

For the endpoints with several verbs you will need to subscribe to each individual event. For example if you want an event to trigger whenever an order is either created, updated or deleted you will need to subscribe to order.create, order.update and order.delete.

Events are created in the format “object.verb”, and may include additional verbs other than create, update, delete. Webhook events will include an optional payloadModel, referencing the swagger model being sent. Events of type delete only include the object ID, and not the object itself.

{
"value": {
    "product.create": {
        "description": "Product created",
        "payloadModel": "Product"

    },
    "order.delete": {
        "description": "Order deleted"
    }
}
}

Delivery

We now guarantee delivery of webhook payloads. In an event where we are unable to deliver the payload immediately we will retry several times, where we increase the time between attempts in a span of 30 hours.

This means that if your callback URL becomes unresponsive for a time, you will still receive the payload once it responds again. If the delivery fails constantly over a week the event subscription will be disabled with status DISABLED_TOO_MANY_ERRORS. A successful delivery “resets” this counter. You can check the status of your event by running GET /event/subscription. You can also re-enable a disabled event via PUT /event/subscription/{id}.

Subscribing to an event

POST https://tripletex.no/v2/event/subscription

{
"event": "product.create",
"targetUrl": "https://your.receiver",
"fields": "(optional) fields from the triggering object to send",
"authHeaderName": "(optional) custom header name, e.g. Authorization",
"authHeaderValue": "(optional) custom header value, e.g. Bearer abc123"
}

“fields” is an optional parameter, and follows the same format as in API2. If you made a call to GET /v2/product/{ID} with a fields parameter, you can use the same fields to get the same response from a subscription to product.*.

Authentication for callback

It is recommended to set up some form of authentication against the targetUrl callback, to prevent misuse. At the moment, three authentication mechanisms are supported:

• (Recommended) Custom authentication header. The fields authHeaderName and authHeaderValue allow for custom authentication headers. These will be sent as-is for every webhook POST callback. For example, if you specify the fields { “authHeaderName”: “Authorization”, “authHeaderValue”: “Bearer abc123”}, each webhook will have the Authorization header set with value Bearer abc123.

• Basic authentication as a part of the URL. Username and password specified as a part of the URL will be sent as an Authorization header when performing callbacks. Example: https://username:password@myintegration.example/tripletex. Username and password will here be sent following the basic authentication protocol.

• Include secret token as query/path parameters. Example: https://myintegration.example/tripletex?token=secret123. This is less recommended than basic authentication, but also supported.

These are the supported mechanisms supported right now. If you have need for more complicated authentication, please let us know and we will consider adding additional mechanisms.

Syncing

If you set up a subscription, give it a few seconds to propagate to all servers, and then sync up all data from e.g. GET /v2/product.

Remember to check the version number of objects loaded through bulk sync and webhooks. For now we recommend having a nightly sync to make sure everything is loaded. Note that if an object is modified several times in rapid succession, the webhook system might skip over a version number or two, but sends over the latest version.

WebHook format

POST <url specified in the subscription>

{
	"subscriptionId": ###,
	"event": "object.verb",
	"id": ###, // Event triggering object's id (Because if *.delete, then "value" below will be null)
	"value": {... single object, optionally filtered by fields ...}
}
Subscription status
GET /v2/event/subscription

Subscription status

GET /v2/event/subscription

{
	..........
	"values": [
		{
			"id": 1,
			"version": 0, // Simply shows how many times this record has been modified (using PUT)
			"url": "https://tripletex.no/v2/event/subscription/1",
			"event": "product.create",
			"targetUrl": "http://webhook.target.io/foo",
			"fields": "*,currency(*)",
			"status": "ACTIVE"
		}
	]
}

The system might set a subscription’s status to DISABLED_TOO_MANY_ERRORS if delivery of an event payload has failed too many times. It is possible to change the status back to ACTIVE from this status.