Using webhooks for modifications in a list

With a webhook, Laposta sends a message to your server as soon as something changes in a list. This allows you to keep your own database in sync without having to continuously query Laposta for updates.

When do you use a webhook?

You use a webhook for modifications that take place in Laposta: someone signs up via a subscribe form, updates their details in the preference centre, or unsubscribes via the unsubscribe link. For modifications that originate from your own system, take a look at synchronising subscribers.

You can configure a webhook for three events:

Event	When is the message sent?
`subscribed`	A subscriber is added to the list.
`modified`	The details of an existing subscriber change.
`deactivated`	A subscriber unsubscribes or is deleted.

Configuring a webhook

Build a URL that can receive messages

Create an address on your own server that accepts a POST request with JSON. Respond quickly with a 200 status code and process the message in the background afterwards.

Register the webhook

curl

curl https://api.laposta.nl/v2/webhook \
  -u YOUR_API_KEY: \
  -d list_id=BaImMu3JZA \
  -d event=subscribed \
  -d url=https://example.net/laposta-webhook \
  -d blocked=false

PHP

$laposta = new Laposta('YOUR_API_KEY');
$webhook = $laposta->webhookApi()->create('BaImMu3JZA', [
    'event' => 'subscribed',
    'url' => 'https://example.net/laposta-webhook',
    'blocked' => false,
]);

Save the secret returned in the response. You can use this later to verify that an incoming message genuinely comes from Laposta.

Verify the signature for every message

Laposta signs every message with that secret. Compare the signature before doing anything with the content, otherwise anyone who knows your URL could insert data into your system.

Things to keep in mind

Process the message in the background, after you have responded to the request. If it takes too long on your end, the call will time out and you will not be sure whether you have received everything.
Expect duplicate messages. When in doubt, Laposta will resend a message. Make sure your system can process the same message twice without creating a duplicate subscriber, for example.
Temporarily disable a webhook instead of deleting it. If you are going to perform maintenance on your server, set blocked to true using Edit webhook. This preserves the registration and the secret.
Modifications via the API also trigger the webhook. If you update a subscriber yourself via the API, the modified webhook will also fire. Take this into account in your own code, otherwise you will immediately send the same modification straight back to Laposta.

Synchronising subscribers through the API

Keep your list in sync with your webshop or CRM: adding, updating, unsubscribing and…

Add webhook

All parameters of the webhook object, including the signing secret.

What are common mistakes with the API?

Pitfalls when integrating with the Laposta API, including the error message you get and…