How to handle webhook notifications?

You can use webhooks to receive an event every time someone signed up to your team, or when someone is added or removed from your subscribers list.

Authentication

All webhooks will be signed by a signing secret, unique to each workspace. You can find the signing secret in your workspace 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.

When someone joins your team

{
  "data": {
    "type": "team-signup",
    "id": "f4663bcc-cf03-4a88-8b04-ddc9370de5ef",
    "name": "someone@example.com",
    "email": "John Doe",
    "workspace": "My Workspace",
    "role": "member"
  }
}

When a subscriber was added

{
  "data": {
    "type": "subscriber-added",
    "id": "f4663bcc-cf03-4a88-8b04-ddc9370de5ef",
    "email": "someone@example.com",
    "name": "John Doe",
    "verified_at": "2023-10-16T07:05:14.931866Z"
  }
}

When a subscriber was removed

{
  "data": {
    "type": "subscriber-removed",
    "id": "f4663bcc-cf03-4a88-8b04-ddc9370de5ef",
    "email": "someone@example.com"
  }
}

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 workspace settings. While it is not mandatory to verify incoming webhooks, we still suggest you do it.

$signature = request()->header('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.