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.

​
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.
Status CodeSemanticsMarked As DeliveredWill Retry
200Event received.✅ Yes❌ No
201Event received.✅ Yes❌ No
202Event received and will be handled asynchronously.✅ Yes❌ No
400Event was not understood.❌ No❌ No
401Sender could not be authenticated (signature fallacy - more below).❌ No❌ No
404Incorrect webhook endpoint URL.❌ No❌ No
429Too many requests. Retry later.❌ No✅ Yes
503Service unavailable. Retry later.❌ No✅ Yes
50xService is down.❌ No❌ No

​
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 a confirmation workflow to be fully activated.

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 length: 500

Body

application/json · object

An event object. Refer to the schema in the Lucca API Reference for the corresponding API version.

Response

Accepted.

Message successfully received for asynchronous processing.