> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.laposta.org/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.laposta.org/_mcp/server.

# Using webhooks for modifications in a list

> With a webhook, Laposta notifies your system as soon as someone subscribes, unsubscribes or modifies their details.

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](/relaties-synchroniseren-via-de-api).

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

Register your URL and the desired event with Laposta:

**`curl`**

```bash title="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`**

```php title="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](/webhooks/webhook-wijzigen). 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.

## Related articles

#### [Synchronising subscribers through the API](/relaties-synchroniseren-via-de-api)

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

#### [Add webhook](/webhooks/webhook-toevoegen)

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

#### [What are common mistakes with the API?](/veelgemaakte-fouten-met-de-api)

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