> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luccasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Receive events

> How to respond to a POST request against your endpoint.

Here are the specifications for a webhook client API endpoint. Please conform to it
whenever deploying a webhook listener on your side.

#### Timeout

Respond as fast as possible, or Lucca may suspend this webhook-endpoint activation and no
longer send events. In other words, you should handle events asynchronously: save them upon
receiving it, respond with a 202, then plan processing it. The current timeout is 3 seconds.

#### Response Status Codes

Your webhook endpoint may respond with the following HTTP status codes. Depending on the code,
Lucca may retry sending the event later, or suspend the endpoint if it is deemed unreachable.

| Status Code | Semantics                                                           | Marked as Delivered | Will retry | Suspend the Endpoint immediately |
| :---------- | :------------------------------------------------------------------ | :------------------ | :--------- | :------------------------------- |
| `2xx`       | Event received.                                                     | ✅ Yes               | ❌ No       | ❌ No                             |
| `400`       | Event was not understood.                                           | ❌ No                | ✅ Yes      | ❌ No                             |
| `401`       | Sender could not be authenticated (signature fallacy - more below). | ❌ No                | ✅ Yes      | ❌ No                             |
| `404`       | Incorrect webhook endpoint URL.                                     | ❌ No                | ❌ No       | ✅ Yes                            |
| `410`       | Endpoint is gone.                                                   | ❌ No                | ❌ No       | ✅ Yes                            |
| `429`       | Too many requests. Retry later.                                     | ❌ No                | ✅ Yes      | ❌ No                             |
| `503`       | Service unavailable. Retry later.                                   | ❌ No                | ✅ Yes      | ❌ No                             |
| `5xx`       | Service is down.                                                    | ❌ No                | ✅ Yes      | ❌ No                             |

<Note>As we refine our implementation, we may stop retrying on more 4xx/5xx status codes depending on their semantics.</Note>

#### Make sure to validate events

In order to protect your endpoint, [validate incoming events](./validate).

#### Implement the activation workflow

Once your endpoint is declared, it must [pass an activation challenge](./spec-activate)
to be fully activated.

#### Automatic suspension

If your endpoint keeps failing (non-2xx responses) over a certain threshold, we may
automatically suspend it. You would then have to fix it then re-activate it from the api or the interface on `https://{yourdomain}.ilucca.{net|ch}/integrations/endpoints`.


## OpenAPI

````yaml webhook-client-api POST /{webhook-endpoint}
openapi: 3.1.0
info:
  title: webhook-client
  description: |-
    API reference for a webhook-client implementation, i.e. a endpoint
    that receives events from the Lucca API.
  version: '1.0'
  contact:
    name: API Support
    url: https://support.lucca.fr
    email: contact@luccasoftware.com
  license:
    name: Unlicensed
    url: https://www.luccasoftware.com
servers:
  - url: https://{domain}
    variables:
      domain:
        default: your-domain.com
security: []
tags:
  - name: Webhooks
    description: Webhooks.
paths:
  /{webhook-endpoint}:
    parameters:
      - in: path
        name: webhook-endpoint
        description: Name of the webhook-endpoint on your server.
        required: true
        schema:
          type: string
          maxLength: 500
    post:
      tags:
        - Webhooks
      summary: Receive events
      description: Webhook event receiver, to be implemented on the client-side.
      operationId: receive-events
      parameters:
        - in: header
          name: Lucca-Signature
          description: Signature of the message
          required: true
          schema:
            type: string
        - in: header
          name: Lucca-Timestamp
          description: Timestamp of the message
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              description: >-
                Refer to the documentation for the [event
                schema](/api-reference/latest/events/event).
              type: object
              additionalProperties: true
      responses:
        '202':
          description: |-
            Accepted.

            Message successfully received for asynchronous processing.
        '400':
          description: |-
            Bad request.

            Invalid Event received.
        '401':
          description: |-
            Unauthorized.

            Signature or timestamp mismatch.
        '404':
          description: |-
            Not Found.

            Webhook receiver endpoint not found.
        '422':
          description: |-
            Unprocessable Content.

            Event type should not be processed on this webhook.
        '500':
          description: |-
            Internal Server Error.

            Retry sending this message again later.
        '503':
          description: |-
            Service Unavailable.

            Server is overloaded, will try sending this message again later.
      security: []

````