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

# Webhooks overview

> Consignease webhooks allow you to receive event notifications from Consignease.

A webhook is an *event-driven* method of communication between applications.

Unlike typical APIs where you would need to poll for data very frequently to get it "real-time", webhooks only send data when there is an event to trigger the webhook. This makes webhooks seem "real-time", but it's important to note that they are asynchronous.

## Consignease webhooks

Consignease webhooks allow you to receive event notifications from Consignease, such as when a user is created or updated. When an event occurs, Consignease will send an HTTP `POST` request to your webhook endpoint configured for the event type. The payload carries a JSON object. You can then use the information from the request's JSON payload to trigger actions in your app, such as sending a notification or updating a database.

Consignease uses [Svix](https://svix.com/) to send our webhooks.

You can find the Webhook signing secret when you select the endpoint you created on the [**Webhooks**](https://dashboard.consignease.com/last-active?path=webhooks) page in the Consignease Dashboard.

## Supported events  

To find a list of all the events Consignease supports:

* From the documentation visit the [webhook events](https://docs.consignease.com/webhooks/events) tab
* Or from the dashboard:
  1. In the Consignease Dashboard, navigate to **Settings → Webhooks**
  2. Select the **Event Catalog** tab

## Payload structure

The payload of a webhook is a JSON object that contains the following properties:

* `data`: contains the actual payload sent by Consignease. The payload can be a different object depending on the `event` type. For example, for `user.*` events, the payload will always be the [**User**](https:docs.consignease.com/) object.
* `object`: always set to `event`.
* `type`: the type of event that triggered the webhook.
* `timestamp`: timestamp in milliseconds of when the event occurred.
* `instance_id`: the identifier of your Consignease instance.

The following example shows the payload of a `user.created` event:

```json theme={null}
{
  "data": {
    "birthday": "",
    "created_at": 1654012591514,
    "email_addresses": [
      {
        "email_address": "example@example.org",
        "id": "idn_29w83yL7CwVlJXylYLxcslromF1",
        "linked_to": [],
        "object": "email_address",
        "verification": {
          "status": "verified",
          "strategy": "ticket"
        }
      }
    ],
    "external_accounts": [],
    "external_id": "567772",
    "first_name": "Example",
    "gender": "",
    "id": "user_29w83sxmDNGwOuEthce5gg56FcC",
    "image_url": "https://img.consignease.com/xxxxxx",
    "last_name": "Example",
    "last_sign_in_at": 1654012591514,
    "object": "user",
    "password_enabled": true,
    "phone_numbers": [],
    "primary_email_address_id": "idn_29w83yL7CwVlJXylYLxcslromF1",
    "primary_phone_number_id": null,
    "primary_web3_wallet_id": null,
    "private_metadata": {},
    "profile_image_url": "https://www.gravatar.com/avatar?d=mp",
    "public_metadata": {},
    "two_factor_enabled": false,
    "unsafe_metadata": {},
    "updated_at": 1654012591835,
    "username": null,
    "web3_wallets": []
  },
  "instance_id": "ins_123",
  "object": "event",
  "timestamp": 1654012591835,
  "type": "user.created"
}
```

The payload should always be treated as unsafe until you validate the incoming webhook. Webhooks will originate from another server and be sent to your application as a POST request. A bad actor would fake a webhook event to try and gain access to your application or data.

## How Consignease handles delivery issues

### Retry

Svix will use a set schedule and retry any webhooks that fail. To see the up-to-date schedule, see the [Svix Retry Schedule](https://docs.svix.com/retries).

If Svix is attempting and failing to send a webhook, and that endpoint is removed or disabled from the [**Webhooks**](https://dashboard.consignease.com/last-active?path=webhooks) page in the Consignease Dashboard, then the attempts will also be disabled.

### Replay

If a webhook message or multiple webhook messages fail to send, you have the option to replay the webhook messages. This protects against your service having downtime or against a misconfigured endpoint.

To replay webhook messages:

1. In the Consignease Dashboard, navigate to the [**Webhooks**](https://dashboard.consignease.com/last-active?path=webhooks) page.
2. Select the affected endpoint.
3. In the **Message Attempts** section, next to the message you want to replay, select the menu icon on the right side, and then select **Replay**.
4. The **Replay Messages** menu will appear. You can choose to:

* Resend the specific message you selected.
* Resend all failed messages since the first failed message in that date range.
* Resend all missing messages since the first failed message in that date range.

## Sync data to your database

You can find a guide on how to use webhooks to sync your data to your database [here](/docs/webhooks/sync-data).

## Protect your webhooks from abuse

To ensure that the API route receiving the webhook can only be hit by your app, there are a few protections you should put in place:

* **Verify the request signature**: Svix webhook requests are [signed](https://www.wikiwand.com/en/Digital_signature) and can be verified to ensure the request is not malicious. To verify the signature, use Consignease's [`verifyWebhook`](https://docs.consignease.com/sdk/node/verify-webhook) helper. To learn more, see Svix's guide on [how to verify webhooks with the svix libraries](https://docs.svix.com/receiving/verifying-payloads/how) or [how to verify webhooks manually](https://docs.svix.com/receiving/verifying-payloads/how-manual).

* **Only accept requests coming from [Svix's webhook IPs](https://docs.svix.com/webhook-ips.json)**:  To further prevent attackers from flooding your servers or wasting your compute, you can ensure that your webhook-receiving api routes only accept requests coming from [Svix's webhook IPs](https://docs.svix.com/webhook-ips.json), rejecting all other requests.
