---
title: "🇫🇷 Norme · Subscribe to a webhook"
method: POST
path: "/flow-service/v1/webhooks"
tags: ["AFNOR XP Z12-013/FlowService"]
---

# 🇫🇷 Norme · Subscribe to a webhook

`POST /flow-service/v1/webhooks`

This operation creates and configures a new webhook, providing:

- The callback URL

- The metadata to filter on subsets of events


The webhook belongs to the owner of the token and cannot be seen from others:

- It returns an id and a signing key (256 or 512 bits) that should be kept

- The signing key allows to validate the signature of each received event.


How the signature is managed:

- At webhook creation a signing Key is randomly generated in a secure way

  - 256 bits are enough if the random generator is secure 

  - 512 bits are necessary if the generator is not secure

- Each time an event is sent:

  - a SHA-256 fingerprint is generated based on the concatenation of:

    - the JSON payload of the response (as is, no canonical format)

    - a separator : @

    - the current epoch time in seconds

  - a HMAC signature is computed over the fingerprint with the callback signing key

  - the signature is base64 encoded for the transport


The signature and the timestamp are returned in the following headers of the callback:

  - Afnor-Signature is the signature (base64)

  - Afnor-Signature-Timestamp is the epoch timestamp in seconds

## Headers

- `Request-Id` string, uuid
- `Organization-Id` string

## Request body

- WebhookParams
  - `callbackUrl` string, uri, required
  - `flowTypes` FlowType[], nullable
  - `flowDirection` 'In' | 'Out' — Direction of the flow: - `In`: Incoming flow, from the PDP to the OD - `Out`: Outgoing flow, from the OD to the PDP
  - `ackStatus` 'Pending' | 'Ok' | 'Error' — - `Ok`: the following checks have passed: - Anti virus - Integrity checks - Technical rules checks - Unicity checks - `Error`: one of the previous test has failed - `Pending` : the flow is not yet integrated

## Response `200`

OK

- WebhookIdParam
  - `webhookId` string, uuid, nullable
  - `signingKey` string, byte, nullable
  - `createdAt` string, date-time, nullable

---

[API](https://skmtc.net/neotimo/apis/neotimo-api.md) · [All operations](https://skmtc.net/neotimo/apis/neotimo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/neotimo/neotimo-api/revisions/2ecf51b1543e/schema)