Setup configuration

Loading notification configuration from a YAML file

This library provides two ConfigurationStep implementations (from the library django-setup-configuration, see the documentation for more information on how to run setup_configuration): one to configure the service and retry settings, another to configure notification endpoint subscriptions.

To make use of this, you must install the setup-configuration dependency group:

pip install zgw-consumers[setup-configuration]

To add these steps to your configuration steps, add django_setup_configuration to INSTALLED_APPS and add the following settings:

SETUP_CONFIGURATION_STEPS = [
    ...
    # Note the order: NotificationSubscriptionConfigurationStep expects a notification service
    # to have been configured by NotificationConfigurationStep
    "notifications_api_common.contrib.setup_configuration.steps.NotificationConfigurationStep"
    "notifications_api_common.contrib.setup_configuration.steps.NotificationSubscriptionConfigurationStep"
    ...
]

The YAML file that is passed to setup_configuration must set the appropriate flag and fields for both steps:

Example file:

notifications_config_enable: true
notifications_config:

  # DESCRIPTION: The maximum number of automatic retries. After this amount of
  # retries, guaranteed delivery stops trying to deliver the message.
  # DEFAULT VALUE: 7
  # REQUIRED: false
  notification_delivery_max_retries: 7

  # DESCRIPTION: If specified, a factor applied to the exponential backoff. This
  # allows you to tune how quickly automatic retries are performed.
  # DEFAULT VALUE: 25
  # REQUIRED: false
  notification_delivery_retry_backoff: 25

  # DESCRIPTION: An upper limit in seconds to the exponential backoff time.
  # DEFAULT VALUE: 52000
  # REQUIRED: false
  notification_delivery_retry_backoff_max: 52000

  # DESCRIPTION: The base factor used for exponential backoff. This can be increased
  # or decreased to spread retries over a longer or shorter time period.
  # DEFAULT VALUE: 4
  # REQUIRED: false
  notification_delivery_base_factor: 4

  # REQUIRED: true
  notifications_api_service_identifier: notificaties-api

notifications_subscriptions_config_enable: true
notifications_subscriptions_config:

  # REQUIRED: true
  items:
    -

      # DESCRIPTION: A human-friendly identifier to refer to this subscription.
      # REQUIRED: true
      identifier: open-zaak

      # DESCRIPTION: Where to send the notifications (webhook url)
      # REQUIRED: true
      callback_url: https://example.com/api/webhook/

      # DESCRIPTION: Client ID to construct the auth token
      # REQUIRED: true
      client_id: open-notificaties

      # DESCRIPTION: Secret to construct the auth token
      # REQUIRED: true
      secret: modify-this

      # DESCRIPTION: The UUID for this subscription. Must match the UUID of the
      # corresponding `Abonnement` in Open Notificaties.
      # REQUIRED: true
      uuid: 02907e89-1ba8-43e9-a86c-d0534d461316

      # DESCRIPTION: Comma-separated list of channels to subscribe to
      # REQUIRED: true
      channels:
        - example_string

Because notifications_api_service_identifier is required, it might also be useful to use the ServiceConfigurationStep from zgw-consumers to configure the Service object for the notifications API.

Note that the uuid field in your subscriptions config must point to an existing Abonnement in the Open Notificaties service configured through notifications_config.