Webhooks documentation

BasicsLink to this section

The Webhooks make a POST request to the endpoints you specify. The Content-Type header will be application/json.

To set up your webhook endpoints, you'll need to go to the setup page of your application, and find the Notifications > Webhooks section.

Each request body has two keys: event, which is new-feedback or new-reply, and data, which holds the fields described below. Internal notes don't trigger a webhook, and webhooks aren't sent for applications that forward every message to a helpdesk.

Verifying requestsLink to this section

Every request includes two headers:

X-Sender: Always Doorbell
X-Doorbell-Signature: An HMAC-SHA256 hash of the raw request body, as a hex string, using your application's webhook signing secret as the key

You'll find the signing secret in the same Webhooks section. To check that a request came from Doorbell, calculate the hash of the body you received and compare it with the header. In PHP:

PHP

$expected = hash_hmac('sha256', file_get_contents('php://input'), $signingSecret);

if (!hash_equals($expected, $_SERVER['HTTP_X_DOORBELL_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

RetriesLink to this section

Return any 2xx status code to confirm you received the webhook. If your endpoint returns another status code or can't be reached, Doorbell tries again after 10 seconds, 30 seconds, 1 minute (three times), 5 minutes, 10 minutes, 1 hour and 2 hours: up to 10 attempts over about three hours.

Each attempt, successful or not, is recorded as a note on the conversation, with the HTTP status code your endpoint returned.

If 10 deliveries in a row to an endpoint fail, over at least 24 hours, we stop sending to it and email the application's admins. Saving your webhooks again turns it back on.

New FeedbackLink to this section

id: int, the ID of the feedback thread
email: string, the email address of the user who submitted the feedback
url: string, the permalink of the feedback thread
member: object or null, the customer who sent the feedback, with 3 keys: id, name, and email
user_agent: string, the formatted user agent string
parsed_user_agent: object, has 3 keys: platform, browser, and version. Will have empty values if it wasn't submitted from the Javascript SDK
message: string, the message the user sent
sentiment: string, the sentiment of the message. Can have values of positive, neutral, or negative
application: object, has 2 keys: id, and name
properties: array, array of object, with each object containing: type, name, and value. The page the feedback was sent from is included as a Page URL property
attachments: array, the files and screenshots attached to the feedback
tags: array, array of object, with each object containing: id, name, and color
created_at: string, the UTC time string of when the feedback was submitted

Example outputLink to this section

JSON

{
    "event": "new-feedback",
    "data": {
        "id": 467,
        "email": "george@example.com",
        "url": "https:\/\/doorbell.io\/applications\/15\/feedback\/467",
        "member": {
            "id": 168,
            "name": "George",
            "email": "george@example.com"
        },
        "user_agent": "Mozilla\/5.0 AppleWebKit\/537.36 (KHTML, like Gecko; compatible; ClaudeBot\/1.0; +claudebot@anthropic.com)",
        "parsed_user_agent": {
            "platform": null,
            "browser": "ClaudeBot",
            "version": "1.0"
        },
        "message": "Here is the feedback that the user sent",
        "sentiment": "",
        "application": {
            "id": 15,
            "name": "Your Application Name"
        },
        "properties": [
            {
                "type": "boolean",
                "name": "logged_in",
                "value": true
            },
            {
                "type": "integer",
                "name": "user_id",
                "value": 578660
            },
            {
                "type": "string",
                "name": "account_name",
                "value": "My Account"
            },
            {
                "type": "string",
                "name": "Page URL",
                "value": "https:\/\/example.com"
            }
        ],
        "attachments": [],
        "tags": [
            {
                "id": 134,
                "name": "tag1",
                "color": "##2a6b04"
            },
            {
                "id": 135,
                "name": "tag2",
                "color": "##1660f6"
            }
        ],
        "created_at": "2026-10-31 01:36:07"
    }
}

New ReplyLink to this section

id: int, the ID of the reply
email: string, the email address of the user who replied
reply_from_agent: boolean, true if someone on your team replied, false if the customer did
url: string, the permalink of the feedback thread
message: string, the message the user sent
feedback: object, has 3 keys: id, member (see above), and created_at
application: object, has 2 keys: id, and name
attachments: array, the files attached to the reply
agent: object, only when reply_from_agent is true, with 3 keys: id, name, and email
created_at: string, the UTC time string of when the reply was sent

Example reply from memberLink to this section

JSON

{
    "event": "new-reply",
    "data": {
        "id": 892,
        "email": "reply@example.com",
        "reply_from_agent": false,
        "url": "https:\/\/doorbell.io\/applications\/15\/feedback\/467",
        "message": "This is the reply message",
        "feedback": {
            "id": 467,
            "member": {
                "id": 168,
                "name": "George",
                "email": "george@example.com"
            },
            "created_at": "2026-10-31 01:36:07"
        },
        "application": {
            "id": 15,
            "name": "Your Application Name"
        },
        "attachments": [],
        "created_at": "2026-10-31 01:51:07"
    }
}

Example reply from agentLink to this section

JSON

{
    "event": "new-reply",
    "data": {
        "id": 892,
        "email": "reply@example.com",
        "reply_from_agent": true,
        "url": "https:\/\/doorbell.io\/applications\/15\/feedback\/467",
        "message": "This is the reply message",
        "feedback": {
            "id": 467,
            "member": {
                "id": 168,
                "name": "George",
                "email": "george@example.com"
            },
            "created_at": "2026-10-31 01:36:07"
        },
        "application": {
            "id": 15,
            "name": "Your Application Name"
        },
        "attachments": [],
        "created_at": "2026-10-31 01:51:07",
        "agent": {
            "id": 708,
            "name": "Gilbert",
            "email": "gilbert@example.org"
        }
    }
}

To see real requests before you build your endpoint, point a webhook at a request inspector such as webhook.site.