Webhooks

You can use webhooks to receive an event every time a secret is either opened, or voided due to exceeding the expiration date, which is 30 days by default. You can also receive a webhook when someone shared a secret via your public sharing url.

Authentication

All webhooks will be signed by a signing secret, unique to your account. You can find the signing secret in your account settings. You don't have to validate the incoming request, but we highly suggested you do it.

Payload

The payload contains the relevant information you may handle in your app. The id (UUID) of your secret, as well as the type of the event and the label. open_count is the current count on how often this secret was already opened. open_limit is the limit you set when creating the secret. This ranges from 1 to 5, or 0 when no limit is set. expired is the indicator whether or not the open limit was reached before open count is equal to open limit.

Expired secrets are automatically voided and receive no further webhooks.

Payload when a secret is opened

{
    "data": {
        "id": "dd5ff91d-f906-4123-9058-c9d7163d6d69",
        "type": "secret_opened_successful",
        "label": "Webhook Test",
        "open_count": 1,
        "open_limit": 1,
        "expired": false
    }
}

Payload when a secret is created via your public sharing url

{
    "data": {
        "type": "public_shared_successful",
        "email_receiver": "you@example.com",
        "email_sharer": "sharer@company.com",
        "expires_at": "2023-02-16 17:44:27"
    }
}

Verify incoming webhooks

To make sure the payload has not been tampered with, you can verify all incoming webhooks. You can find your signing secret in your account settings. While it is not mandatory to verify incoming webhooks, we still suggest you do it.

We send the signature with the name InPrivy-Signature.

$signature = request()->header('InPrivy-Signature');

$signingSecret = 'your-signing-secret';

$computedSignature = hash_hmac('sha256', request()->getContent(), $signingSecret);

if (hash_equals($signature, $computedSignature)) {
    // Signature verified, do your thing ...
}

Retries

If we receive an HTTP 200 OK response from your webhook URL, we consider the webhook successful. If your application returns anything else, including 301 or 302 redirects, we mark the webhook as failed and will resend the same payload again.

We will try to send the webhook up to 3 times. If we receive a non-HTTP 200 response code, or a timeout (of 3 seconds or more) for 3 times, we consider the webhook failed and will not resend that particular event.