notifications-webhook.yaml

openapi: 3.0.3
info:
  title: Notifications webhook receiver
  version: v1
  description: API Specification to be able to receive notifications from the NRC
  contact:
    name: VNG Realisatie
    url: https://github.com/VNG-Realisatie/gemma-zaken
paths:
  /{webhooks_path}:
    post:
      operationId: notification_receive
      description: Ontvang notificaties via webhook
      parameters:
      - in: header
        name: Content-Type
        schema:
          type: string
          enum:
          - application/json
        description: Content type of the request body.
        required: true
      - in: path
        name: webhooks_path
        schema:
          type: string
        required: true
      tags:
      - Notificaties
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Notificatie'
        required: true
      security:
      - JWT-Claims:
        - notificaties.publiceren
      responses:
        '204':
          headers:
            API-version:
              schema:
                type: string
              description: 'Geeft een specifieke API-versie aan in de context van
                een specifieke aanroep. Voorbeeld: 1.2.1.'
          description: No response body
        '400':
          headers:
            API-version:
              schema:
                type: string
              description: 'Geeft een specifieke API-versie aan in de context van
                een specifieke aanroep. Voorbeeld: 1.2.1.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidatieFout'
          description: Bad request
        '401':
          headers:
            API-version:
              schema:
                type: string
              description: 'Geeft een specifieke API-versie aan in de context van
                een specifieke aanroep. Voorbeeld: 1.2.1.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Fout'
          description: Unauthorized
        '403':
          headers:
            API-version:
              schema:
                type: string
              description: 'Geeft een specifieke API-versie aan in de context van
                een specifieke aanroep. Voorbeeld: 1.2.1.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Fout'
          description: Forbidden
        '429':
          headers:
            API-version:
              schema:
                type: string
              description: 'Geeft een specifieke API-versie aan in de context van
                een specifieke aanroep. Voorbeeld: 1.2.1.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Fout'
          description: Too many requests
        '500':
          headers:
            API-version:
              schema:
                type: string
              description: 'Geeft een specifieke API-versie aan in de context van
                een specifieke aanroep. Voorbeeld: 1.2.1.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Fout'
          description: Internal server error
        '502':
          headers:
            API-version:
              schema:
                type: string
              description: 'Geeft een specifieke API-versie aan in de context van
                een specifieke aanroep. Voorbeeld: 1.2.1.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Fout'
          description: Bad gateway
        '503':
          headers:
            API-version:
              schema:
                type: string
              description: 'Geeft een specifieke API-versie aan in de context van
                een specifieke aanroep. Voorbeeld: 1.2.1.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Fout'
          description: Service unavailable
components:
  schemas:
    FieldValidationError:
      type: object
      description: Formaat van validatiefouten.
      properties:
        name:
          type: string
          description: Naam van het veld met ongeldige gegevens
        code:
          type: string
          description: Systeemcode die het type fout aangeeft
        reason:
          type: string
          description: Uitleg wat er precies fout is met de gegevens
      required:
      - code
      - name
      - reason
    Fout:
      type: object
      description: Formaat van HTTP 4xx en 5xx fouten.
      properties:
        type:
          type: string
          description: URI referentie naar het type fout, bedoeld voor developers
        code:
          type: string
          description: Systeemcode die het type fout aangeeft
        title:
          type: string
          description: Generieke titel voor het type fout
        status:
          type: integer
          description: De HTTP status code
        detail:
          type: string
          description: Extra informatie bij de fout, indien beschikbaar
        instance:
          type: string
          description: URI met referentie naar dit specifiek voorkomen van de fout.
            Deze kan gebruikt worden in combinatie met server logs, bijvoorbeeld.
      required:
      - code
      - detail
      - instance
      - status
      - title
    Notificatie:
      type: object
      properties:
        kanaal:
          type: string
          description: De naam van het kanaal (`KANAAL.naam`) waar het bericht op
            moet worden gepubliceerd.
          maxLength: 50
        hoofdObject:
          type: string
          format: uri
          description: URL-referentie naar het hoofd object van de publicerende API
            die betrekking heeft op de `resource`.
        resource:
          type: string
          description: De resourcenaam waar de notificatie over gaat.
          maxLength: 100
        resourceUrl:
          type: string
          format: uri
          description: URL-referentie naar de `resource` van de publicerende API.
        actie:
          type: string
          description: De actie die door de publicerende API is gedaan. De publicerende
            API specificeert de toegestane acties.
          maxLength: 100
        aanmaakdatum:
          type: string
          format: date-time
          description: Datum en tijd waarop de actie heeft plaatsgevonden.
        kenmerken:
          type: object
          additionalProperties:
            type: string
            title: kenmerk
            description: Een waarde behorende bij de sleutel.
            maxLength: 1000
          description: Mapping van kenmerken (sleutel/waarde) van de notificatie.
            De publicerende API specificeert de toegestane kenmerken.
      required:
      - aanmaakdatum
      - actie
      - hoofdObject
      - kanaal
      - resource
      - resourceUrl
    ValidatieFout:
      type: object
      description: Formaat van HTTP 4xx en 5xx fouten.
      properties:
        type:
          type: string
          description: URI referentie naar het type fout, bedoeld voor developers
        code:
          type: string
          description: Systeemcode die het type fout aangeeft
        title:
          type: string
          description: Generieke titel voor het type fout
        status:
          type: integer
          description: De HTTP status code
        detail:
          type: string
          description: Extra informatie bij de fout, indien beschikbaar
        instance:
          type: string
          description: URI met referentie naar dit specifiek voorkomen van de fout.
            Deze kan gebruikt worden in combinatie met server logs, bijvoorbeeld.
        invalidParams:
          type: array
          items:
            $ref: '#/components/schemas/FieldValidationError'
      required:
      - code
      - detail
      - instance
      - invalidParams
      - status
      - title