# Listing Status Webhooks

Source: https://developer.synup.com/listings/status-webhooks

## Listing Status Webhooks

Webhooks provide real-time notifications about the status of your business listings. When enabled, the system automatically sends HTTP POST requests to your specified URL whenever there are important listing updates.

### Setup Instructions

#### Enabling Webhooks

Follow these steps to enable and configure webhooks for your account:

- Enable Webhooks – Contact support to activate webhook functionality.
- Configure the Webhook URL in your account settings:
- Log into your account.
- Click your profile picture (top right).
- Go to Settings.
- Select Notification Settings.
- Enter your webhook URL.

### Webhook Events

#### Successful Submission

When a business listing is successfully synced with a directory, the system sends a webhook notification with the following payload:
```json
{
  "event": "listing.submission",
  "data": {
    "location_id": "TG9jYXRpb246MTAxNDA=",
    "site": {
      "id": 277,
      "name": "Example Site",
      "url": "example.com"
    }
  },
  "status": "success",
  "live_link": "https://example.com/business/4e355942-23ef-44b8-b9f7-3aff9a97fddc"
}
```

#### Failed Submission
If a listing sync fails due to non-retriable errors, the system sends a webhook notification with an error message.

Examples of non-retriable errors include:
- **City Not Found**
- **Unable To Claim**

Example error payload:

```json
{
  "event": "listing.submission",
  "data": {
    "location_id": "TG9jYXRpb246MTAxNDA=",
    "site": {
      "id": 193,
      "name": "Example Site",
      "url": "example.com"
    }
  },
  "status": "incomplete",
  "error_message": "Unable to Claim"
}
```

> **Note:** For backward compatibility, all webhook payloads include a `business_id` field for integrations that rely on integer Location IDs.

### Best Practices

- Implement retry logic in your webhook handler to handle temporary failures.
- Process webhooks asynchronously to avoid timeouts and improve performance.
- Validate the webhook payload before processing to ensure data integrity.

Following these best practices will help you efficiently manage listing status updates and ensure a reliable webhook integration.