Open Notificaties configuration (admin)

Before you can work with Open Notificaties after installation, a few settings need to be configured first. We assume that Open Notificaties is used together with Open Zaak.

Configure Notificaties API

Open Notificaties uses the Autorisaties API to check if the sender is authorized to send notifications. Open Zaak offers an Autorisaties API and below we assume you use this one.

  1. Configure the Open Zaak Autorisaties API endpoint (so Open Notificaties knows where to check for the proper autorisations):

    1. Navigate to Configuratie > Autorisatiecomponentconfiguratie

    2. Fill out the form:

      • API root: The URL to the Notificaties API. For example: https://open-zaak.gemeente.local/autorisaties/api/v1/.

      • Component: Notificaties API

    3. Click Opslaan.

Adding new component to send notifications

Below are the general steps to allow an application to send notifications and using Open Zaak as the example.

  1. Configure the credentials for the Open Zaak Autorisaties API (so Open Notificaties can access the Autorisaties API):

    1. Navigate to API Autorisaties > Services

    2. Click Service toevoegen.

    3. Fill out the form:

      • Api root url: The URL of the Open Zaak Autorisaties API endpoint

      • Label: For example: Open Zaak Autorisaties

      • Client id: For example: open-notificaties

      • Secret: Some random string

      • Authorization type: ZGW client_id + secret

      • Gebruikers ID: Same as the Client ID

      • Gebruikersweergave: For example: Open Notificaties

      • Service slug: For example: authorization-api-service

      Make sure Open Notificaties is authorized in Open Zaak to access the Autorisaties API by using the same Client ID and Secret as given here.

    4. Click Opslaan.

  2. Then we need to allow Open Zaak to access Open Notificaties (for authentication purposes, so we can then check its authorizations):

    1. Navigate to API Autorisaties > Autorisatiegegevens

    2. Click Autorisatiegegeven toevoegen.

    3. Fill out the form:

      • Client ID: For example: open-zaak

      • Secret: Some random string

      Make sure Open Zaak is configured to use this Client ID and secret to access Open Notificaties.

    4. Click Opslaan.

  3. After that, we need to configure the Notificatiescomponentconfiguratie.

    1. Navigate to Configuratie > Notificatiescomponentconfiguratie and add a new Notifications api service

    2. Fill out the form and use the client ID and secret from step 1c

    3. Click Opslaan on the Service form

    4. Click Opslaan on the Notificatiescomponentconfiguratie form

  4. Finally, we need to add the client ID and secret from step 1c under API Autorisaties > Autorisatiegegevens > Autorisatiegegeven toevoegen

Configure Open Zaak

In case Open Zaak is not configured yet, refer to configuration of Open Zaak. Use the following values for the environment variables used for the setup_configuration command:

  • NOTIF_OPENZAAK_CLIENT_ID: client ID from step 1c above

  • NOTIF_OPENZAAK_SECRET: secret from step 1c above

  • OPENZAAK_NOTIF_CLIENT_ID: client ID from step 2c above

  • OPENZAAK_NOTIF_SECRET: secret from from step 2c above

Add notification consumers

In order to add new consumer webhooks that are subscribed to specific channels, follow these steps:

  1. Ensure your consumer webhook can handle the notification body (see API specification)

  2. Ensure your consumer webhook responds to notifications with a status code in the range 200-209

  3. (Optional) If no Kanaal exists for the resource, create it via the admin interface

    1. Navigate to Notificaties > Kanalen > Kanaal toevoegen

    2. Fill out the form:

      • Naam: the name of the channel

      • Documentatie link: optional, URL that points towards documentation about the channel

      • Filters: optional, comma separated list of attributes on which subscriptions can filter

  4. Configure an Abonnement for the consumer webhook

    1. Navigate to Notificaties > Abonnementen > Abonnement toevoegen

    2. Fill out the form:

    • Callback URL: the URL of the consumer webhook to which Open Notificaties will send notifications

    • Autorisatie header: the authorization header that Open Notificaties will use for its requests to the callback URL

    • Client ID: optional, the client identifier used in the authorization header (in case of JWT)

    • Filters > Kanaal: the channels to which the consumer webhook should be subscribed

    Warning

    The manual describes how to add Abonnementen, but the mechanism to support authentication (JWT or otherwise) does not function properly at the moment. The method to add Abonnementen as described above is a workaround for this issue

All done!