Webhooks

With webhooks in Picqer, you can get push notifications when certain events happen in your Picqer account. With these webhooks, you do not need to poll the API anymore to see if a picklist is closed. You can just 'subscribe' to this event with our webhooks.

New to webhooks?

Receiving and processing webhooks is really simple. To give you a head start as a beginner, view our PHP example of a 4-line script that receives and processes a webhook.

If you are using the PHP Client, you can use the Webhook helper to easily receive webhooks.

Available events

We have a couple of events you can subscribe to. If you need an event we do not support yet, please let us know.

Payload

When an event is triggered, you get a POST request on the given address. In the POST data we give information about the trigger and all data about the object involved. An example of the request we send you:

View examples of all webhook types

We expect you to give a 200 OK, 201 Created or 202 Accepted status code as a response. We ignore the content you send us. You have a maximum of 10 seconds to process the request, otherwise we also see it as a failure and we will retry.

Failures and retries

When we do not get a 200 OK, 201 Created or 202 Accepted status back from you, we consider the call as failed. We will retry to send the message 15 times in 24 hours. After 15 retries we delete the call from our queues.

Important: If a webhook fails too many times, we inactivate the hook. You can only reactivate the hook by registering a new one with the steps below. So make sure you handle possible errors on your side properly. Perhaps ignore a call and give a 200 state if you cannot process the request after multiple tries.

Registering your hooks

Adding and removing your subscriptions to these events, or 'hooks' as we call them, is possible via the API as well as via your Picqer account. Below you find the documentation for managing your hooks via the API.

Debug logging

For easier debugging, you can see details about recent deliveries for registered webhooks in your Picqer account. Go to Settings > Webhooks to see the webhooks. On the details page you see the recent deliveries Picqer made for this webhook.

Attributes

Get all hooks

Get single hook

Create new hook

Webhooks can be created at Settings > Webhooks, or you can create new webhooks via the API.

Deactivate a hook

To deactivate a hook you can use this delete call. This call will not actually delete the webhook, but it will deactivate the webhook.

Validating webhooks

If you provide a secret while registering the webhook, we will sign deliveries of the webhook with a X-Picqer-Signature header.

The signature is created with an HMAC hash, using SHA256. We use the whole body of the request as the signed content.

For example, in PHP you can check the signature as follows:

$webhookPayloadRaw = file_get_contents('php://input');
$checkingSignature = base64_encode(
        hash_hmac('sha256', $webhookPayloadRaw, 'your-provided-secret', true)
    );

$isSignatureValid = hash_equals($checkingSignature, $_SERVER['HTTP_X_PICQER_SIGNATURE']);

If you are using the PHP Client, you can use the Webhook helper to easily check the webhook signature.