Receive Webhook on the server side

Request headers and authentication

Webhook requests will carry Bearer Token for authentication. Your server should:

1. Read the Authorization information from the request header.
2. Extract Bearer Token.
3. Compare with the token stored securely on the server side.
4. Reject the request when verification fails.
5. Parse and process the payload after the verification is successful.

Do not judge whether the callback is legitimate based only on the source IP, and do not record the Token in the ordinary business log.

Payload

The complete fields and version of the payload are subject to Geelab's current Webhook Payload Reference. Your server should be able to recognize at least:

• Event type.
• Request ID.
• Application and endpoints information.
• Event time.
• Device ID or identifying information.
• Risk signal (if this event hits).

After receiving the Request ID, you can call the Server API according to business needs to obtain more complete event information. Don’t make high-risk decisions solely on client-reported content.

Event type

If you subscribe to "all identified events", the server should be able to handle normal events and high-risk events. If you subscribe to "Only high-risk events", the server should still verify based on the event type and risk signal in the payload, and do not assume that each callback contains the same fields.

Version compatible

Recommendations when handling Payload:

• Use event type and field name judgment instead of relying on field order.
• Maintain compatibility with new fields and ignore unknown fields that are temporarily unnecessary.
• Tolerance for missing optional fields.
• Save the payload version or version information in the request header (if provided).
• Follow Geelab's update notes and test before upgrading.

Don't hardcode the complete payload structure into a strict string match that cannot evolve.

Delivery semantics

The current version of Webhook adopts an asynchronous, single-delivery model: the platform only initiates one HTTP request for each event, and will not automatically retry because the target service returns an error or times out. Your receiving service should do its own idempotent processing and confirm the final result through the delivery log.

Different events may be sent in parallel, so arrival is not guaranteed to occur exactly at the time of event occurrence. When processing business with sequential dependencies, please combine the event time, business status and Request ID to determine whether it can be executed. Do not rely solely on the arrival sequence.

Illustration: Webhook request and event information