Skip to main content
POST
/
{webhook-endpoint}
Receive events
curl --request POST \
  --url https://{domain}/{webhook-endpoint} \
  --header 'Content-Type: application/json' \
  --header 'Lucca-Signature: <lucca-signature>' \
  --header 'Lucca-Timestamp: <lucca-timestamp>' \
  --data '{}'
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 CodeSemanticsMarked as DeliveredWill retrySuspend the Endpoint immediately
2xxEvent received.✅ Yes❌ No❌ No
400Event was not understood.❌ No✅ Yes❌ No
401Sender could not be authenticated (signature fallacy - more below).❌ No✅ Yes❌ No
404Incorrect webhook endpoint URL.❌ No❌ No✅ Yes
410Endpoint is gone.❌ No❌ No✅ Yes
429Too many requests. Retry later.❌ No✅ Yes❌ No
503Service unavailable. Retry later.❌ No✅ Yes❌ No
5xxService is down.❌ No✅ Yes❌ No
As we refine our implementation, we may stop retrying on more 4xx/5xx status codes depending on their semantics.

​
Make sure to validate events

In order to protect your endpoint, validate incoming events.

​
Implement the activation workflow

Once your endpoint is declared, it must pass an activation challenge 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.

Headers

​
Lucca-Signature
string
required

Signature of the message

​
Lucca-Timestamp
string
required

Timestamp of the message

Path Parameters

​
webhook-endpoint
string
required

Name of the webhook-endpoint on your server.

Maximum string length: 500

Body

application/json

Refer to the documentation for the event schema.

Response

Accepted.

Message successfully received for asynchronous processing.