Skip to main content

Set up and manage webhooks​

France only

Learn how to create, verify, and manage webhook subscriptions for the AFNOR connector API. Webhooks allow you to receive real-time notifications about document events without repeatedly polling the API.

Prerequisites​

Webhook lifecycle​

  1. Create a webhook subscription and specify the events to monitor.
  2. Store the returned webhookId and signingKey securely.
  3. Receive notifications at your callbackUrl.
  4. Validate each notification using the Afnor-Signature and Afnor-Signature-Timestamp headers.
  5. Process the notification after successful validation.
  6. Retrieve your webhook subscriptions when you need to manage them.
  7. Delete a subscription when it is no longer required.

Step 1: Create a webhook subscription

Register a listener endpoint to receive real-time notifications when documents matching your subscription are processed.

You can configure up to 10 webhooks per space.


Endpoint: /network/documents/spaces/connectors/afnor/v1/webhooks


Header parameters:

  • Request-Id: Client-generated unique identifier used to trace logs across requests.
  • Organization-Id: The spaceId of the Jefacture space.

Requires a JSON request body.

curl -L 'https://{{serverURL}}/network/documents/spaces/connectors/afnor/v1/webhooks' \
-H 'Request-Id: 4803c35e-d132-4d4a-a29a-9da5f583b89a' \
-H 'Organization-Id: 60debf1a-e348-46a2-8e28-36403f83b022' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
  "callbackUrl": "[https://your-app.example.com/webhooks/afnor](https://your-app.example.com/webhooks/afnor)",
  "flowDirection": "In",
  "flowTypes": [
    "SupplierInvoice"
  ]
}'

Successful response:

Save both the webhookId and the generated signingKey. You need the signing key to validate incoming webhook notifications.
Keep the signing key secure. Do not expose it in client-side code, logs, or publicly accessible configuration.


{
  "webhookId": "6bf9fa3c-704e-44c7-8dd4-e76d0800c324",
  "signingKey": "jsXizLtzADbksSH5kJ1+U4N6/nkOVOOKCEjLm7TwMqI=",
  "createdAt": "2026-08-25T12:11:41.280443742Z"
}

Step 2: Validate webhook notifications

When Banqup sends a webhook notification, it includes an Afnor-Signature header and an Afnor-Signature-Timestamp header. Use the signing key returned when you created the subscription to validate the notification.


Webhook notification headers:


HeaderRequiredDescription
Afnor-SignatureNoSignature used to validate the webhook notification.
Afnor-Signature-TimestampYesTimestamp associated with the webhook signature, expressed as epoch time in seconds.

Webhook notification body:


The notification contains a JSON payload (Flow schema) with information about the flow that triggered the webhook.


Example:

{
  "flowId": "12345678-1234-1234-1234-123456789012",
  "name": "invoice_12345.xml",
  "flowSyntax": "Factur-X",
  "flowType": "SupplierInvoice",
  "flowDirection": "In",
  "flowProfile": "Basic",
  "processingRule": "B2B",
  "processingRuleSource": "Computed",
  "submittedAt": "2026-08-25T12:11:41Z",
  "updatedAt": "2026-08-25T12:12:03Z",
  "acknowledgement": {
    "status": "Ok"
  }
}

The webhook notification contains flow information. It does not contain the original invoice file itself.


Your webhook endpoint should:

  1. Receive the webhook request.
  2. Read the Afnor-Signature and Afnor-Signature-Timestamp headers.
  3. Validate the signature using the signing key associated with the webhookId.
  4. Process the notification only after the signature has been successfully validated.
  5. Return an HTTP 200 OK response to acknowledge successful receipt.

Use the request body as received when validating the signature. Do not modify the payload before validation.

Keep the signing key secure. Do not expose it in client-side code, logs, or publicly accessible configuration.

Step 3: Retrieve webhook subscriptions

List the webhook subscriptions configured for a Jefacture space.


Endpoint: /network/documents/spaces/connectors/afnor/v1/webhooks


Header parameters:

  • Request-Id: Client-generated unique identifier used to trace logs across requests.
  • Organization-Id: The spaceId of the Jefacture space.

curl -L 'https://{{serverURL}}/network/documents/spaces/connectors/afnor/v1/webhooks' \
-H 'Request-Id: 4803c35e-d132-4d4a-a29a-9da5f583b89a' \
-H 'Organization-Id: 60debf1a-e348-46a2-8e28-36403f83b022' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response:


{
  "count": 1,
  "webhooks": [
    {
      "webhookId": "6bf9fa3c-704e-44c7-8dd4-e76d0800c324",
      "callbackUrl": "[https://your-app.example.com/webhooks/afnor](https://your-app.example.com/webhooks/afnor)",
      "signingKey": "jsXizLtzADbksSH5kJ1+U4N6/nkOVOOKCEjLm7TwMqI=",
      "flowTypes": [
        "SupplierInvoice"
      ],
      "flowDirection": "In",
      "ackStatus": "Ok",
      "createdAt": "2026-08-25T12:11:41.280443742Z"
    }
  ]
}

Webhook subscriptions belong to the owner of the access token used to create them. A webhook can only be managed by its owner.

Step 4: Remove a webhook subscription

Endpoint: /network/documents/spaces/connectors/afnor/v1/webhooks/{webhookId}


Path parameter:

  • webhookId (required): The unique identifier (UUID) of the webhook subscription to delete.

Header parameters:

  • Request-Id: Client-generated unique identifier used to trace logs across requests.
  • Organization-Id: The spaceId of the Jefacture space.

curl -L -X DELETE 'https://{{serverURL}}/network/documents/spaces/connectors/afnor/v1/webhooks/{webhookId}' \
-H 'Request-Id: 4803c35e-d132-4d4a-a29a-9da5f583b89a' \
-H 'Organization-Id: 60debf1a-e348-46a2-8e28-36403f83b022' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response:

The webhook subscription is deleted successfully.