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

# Webhooks Introduction

> Receive real-time notifications when authentication status changes, images are rejected, or service requests are invalidated.

Legitmark sends real-time event notifications to your HTTPS endpoints through webhooks. When a service request state changes, images are rejected during quality control, or a request is invalidated, your endpoint receives a `POST` request with the event payload.

Delivery includes automatic retries with exponential backoff.

<Note>
  Need to set up a webhook destination? Follow the steps in [Getting Started](/partner/getting-started).
</Note>

## Requirements

Your webhook endpoint must meet these requirements:

| Requirement      | Detail                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **HTTPS**        | Destination URL must use HTTPS                                                                                                 |
| **200 response** | Return a `200` status within 30 seconds to acknowledge receipt                                                                 |
| **Idempotency**  | Handle duplicate deliveries — see [Handling Webhooks](/webhook-reference/handling) for deduplication strategies per event type |

## Event Types

All destinations automatically receive every event type. There is no per-event filtering.

<CardGroup cols={3}>
  <Card title="state_change" icon="arrows-rotate" href="/webhook-reference/events#state_change">
    Service request state changed — QC, authentication progress, or final result.
  </Card>

  <Card title="media_rejected" icon="image-slash" href="/webhook-reference/events#media_rejected">
    Uploaded images rejected during quality control.
  </Card>

  <Card title="invalidate_sr" icon="circle-xmark" href="/webhook-reference/events#invalidate_sr">
    Service request cancelled or cannot be processed.
  </Card>
</CardGroup>

## Common Payload Fields

Every webhook event includes these base fields:

| Field          | Type             | Description                                                              |
| -------------- | ---------------- | ------------------------------------------------------------------------ |
| `event_type`   | `string`         | The event identifier (`state_change`, `media_rejected`, `invalidate_sr`) |
| `sr_uuid`      | `string`         | Service request UUID                                                     |
| `reference_id` | `string \| null` | Your internal item ID (the `external_id` you set when creating the SR)   |
| `timestamp`    | `string`         | ISO 8601 timestamp of when the event occurred                            |

## Retries

Failed deliveries (non-2xx response or timeout) are automatically retried with exponential backoff:

| Attempt | Delay        |
| ------- | ------------ |
| 1       | Immediate    |
| 2       | \~5 seconds  |
| 3       | \~5 minutes  |
| 4       | \~30 minutes |
| 5       | \~2 hours    |

After all retries are exhausted, the message is marked as failed. You can view delivery status and retry manually from the [Developer Settings](https://app.legitmark.com/settings/developer).

## Testing

If you don't have an endpoint ready yet, you can use [Svix Play](https://play.svix.com/) to generate a temporary webhook URL for testing. Paste the generated URL as your webhook destination in the [Developer Settings](https://app.legitmark.com/settings/developer), send a test event, and inspect the payload in real time.

## Next Steps

<CardGroup cols={2}>
  <Card title="Event Types" icon="bolt" href="/webhook-reference/events">
    Detailed payload schemas for each event type.
  </Card>

  <Card title="Handling Webhooks" icon="code" href="/webhook-reference/handling">
    Code examples, best practices, and security guidance.
  </Card>
</CardGroup>