Receive Pigeon Webhook Events

When building Pigeon integrations, you might want your applications to receive events as they occur in your Pigeon accounts, so that your backend systems can execute actions accordingly.

Create a webhook subscription to receive events at an HTTPS webhook endpoint. After you register a webhook endpoint, Pigeon can push real-time event data to your application’s webhook endpoint as events happen. Pigeon uses HTTPS to send webhook events to your app as a JSON payload.

Receiving webhook events is particularly useful for listening to asynchronous events such as when a recipient submits a request or feedback is requested on a request.

Getting Started

To start receiving webhook events in your app, create and register a webhook endpoint via the API. Use the Create Webhook Subscription route to setup your webhook.

When creating a new webhook subscription, you can configure your endpoint to specific webhook topics. Each topic represents an event that occurs within the Pigeon application.

Webhook Topics

`request.created`

The request.created topic is triggered when a new request is created. The data object in the event payload represents the new request.

Sample Payload

{
    "event_id": "0b11e21d-85f3-4e30-b3e9-1a260c25070e",
    "topic": "request.created",
    "organization_id": "0",
    "data": {
        "id": "74e85389-2f99-45ab-8535-b986bedd7759",
        "state": "INCOMPLETE_AND_LINK_SENT",
        "owner_id": "0",
        "owner_opened": true,
        "user_opened": true,
        "name": "Request Name",
        "due_date": "2025-01-01T00:00.00",
        "submission_date": "2025-01-01T00:00.00",
        "expiration_date": null,
        "personal_message": null,
        "security_question": null,
        "language": "en-US",
        "reminders": "NONE",
        "items": [
            {
                "id": "1a3126ba-9bce-4096-8d73-f2c704837741",
                "type": "STANDARD",
                "name": "Form Item",
                "description": null,
                "required": true
            },
            {
                "id": "7ad70695-677f-4fd1-92c1-f6c7b3ab132e",
                "type": "E_SIGNATURE",
                "name": "ESignature Item",
                "description": null,
                "required": true
            },
            {
                "id": "f43476bf-2e1b-4ca7-8cba-4522ec75321f",
                "type": "QUESTION",
                "name": "Question Item",
                "description": null,
                "required": true
            }
        ],
        "recipients": [
            {
                "first_name": "Pigeon",
                "last_name": "User",
                "email": "support@pigeondocuments.com",
                "phone": "",
                "request_link": null,
                "auth": "NONE"
            }
        ],
        "collaborators": []
    }
}

`request.updated`

The request.updated topic is triggered when a request is updated. The data object in the event payload represents the updated request.

The event payload also includes an updated object that specifies the attributes that were updated.

Sample Payload

{
    "event_id": "0b11e21d-85f3-4e30-b3e9-1a260c25070e",
    "topic": "request.updated",
    "organization_id": "0",
    "data": {
        "id": "74e85389-2f99-45ab-8535-b986bedd7759",
        "state": "PARTIALLY_SUBMITTED",
        "owner_id": "0",
        "owner_opened": true,
        "user_opened": true,
        "name": "Updated Request Name",
        "due_date": "2025-01-01T00:00.00",
        "submission_date": "2025-01-01T00:00.00",
        "expiration_date": null,
        "personal_message": null,
        "security_question": null,
        "language": "en-US",
        "reminders": "NONE",
        "items": [
            {
                "id": "1a3126ba-9bce-4096-8d73-f2c704837741",
                "type": "STANDARD",
                "name": "Form Item",
                "description": null,
                "required": true
            },
            {
                "id": "7ad70695-677f-4fd1-92c1-f6c7b3ab132e",
                "type": "E_SIGNATURE",
                "name": "ESignature Item",
                "description": null,
                "required": true
            },
            {
                "id": "f43476bf-2e1b-4ca7-8cba-4522ec75321f",
                "type": "QUESTION",
                "name": "Question Item",
                "description": null,
                "required": true
            }
        ],
        "recipients": [
            {
                "first_name": "Pigeon",
                "last_name": "User",
                "email": "support@pigeondocuments.com",
                "phone": "",
                "request_link": null,
                "auth": "NONE"
            }
        ],
        "collaborators": []
    },
    "updated": {
        "name": "Updated Request Name",
        "due_date": "2025-01-01T00:00.00",
    }
}

`request.deleted`

The request.deleted topic is triggered when a request is deleted. The data object in the event payload represents the deleted request.

Sample Payload

{
    "event_id": "0b11e21d-85f3-4e30-b3e9-1a260c25070e",
    "topic": "request.deleted",
    "organization_id": "0",
    "data": {
        "id": "74e85389-2f99-45ab-8535-b986bedd7759",
        "state": "SUBMITTED",
        "owner_id": "0",
        "owner_opened": true,
        "user_opened": true,
        "name": "Updated Request Name",
        "due_date": "2025-01-01T00:00.00",
        "submission_date": "2025-01-01T00:00.00",
        "expiration_date": null,
        "personal_message": null,
        "security_question": null,
        "language": "en-US",
        "reminders": "NONE",
        "items": [
            {
                "id": "1a3126ba-9bce-4096-8d73-f2c704837741",
                "type": "STANDARD",
                "name": "Form Item",
                "description": null,
                "required": true
            },
            {
                "id": "7ad70695-677f-4fd1-92c1-f6c7b3ab132e",
                "type": "E_SIGNATURE",
                "name": "ESignature Item",
                "description": null,
                "required": true
            },
            {
                "id": "f43476bf-2e1b-4ca7-8cba-4522ec75321f",
                "type": "QUESTION",
                "name": "Question Item",
                "description": null,
                "required": true
            }
        ],
        "recipients": [
            {
                "first_name": "Pigeon",
                "last_name": "User",
                "email": "support@pigeondocuments.com",
                "phone": "",
                "request_link": null,
                "auth": "NONE"
            }
        ],
        "collaborators": []
    }
}

`request.submitted`

The request.submitted topic is triggered when a recipient creates a submission for a request. The data object in the event payload represents the request.

The event payload also includes a submission object that includes details related to the submission. This object specifies the following attributes:

Attribute	Type	Description
`recipient`	`object`	The recipient who created the submission
`status`	`enum`	Indicates the completion status of the request (`COMPLETE` or `PARTIAL`)
`message`	`string`	Custom message submitted from recipient
`submitted_at`	`datetime`	Timestamp of submission
`items`	`object[]`	Array of items included in the submission

Sample Payload

{
    "event_id": "0b11e21d-85f3-4e30-b3e9-1a260c25070e",
    "topic": "request.submitted",
    "organization_id": "0",
    "data": {
        "id": "74e85389-2f99-45ab-8535-b986bedd7759",
        "state": "PARTIALLY_SUBMITTED",
        "owner_id": "0",
        "owner_opened": true,
        "user_opened": true,
        "name": "Updated Request Name",
        "due_date": "2025-01-01T00:00.00",
        "submission_date": "2025-01-01T00:00.00",
        "expiration_date": null,
        "personal_message": null,
        "security_question": null,
        "language": "en-US",
        "reminders": "NONE",
        "items": [
            {
                "id": "1a3126ba-9bce-4096-8d73-f2c704837741",
                "type": "STANDARD",
                "name": "Form Item",
                "description": null,
                "required": true
            },
            {
                "id": "7ad70695-677f-4fd1-92c1-f6c7b3ab132e",
                "type": "E_SIGNATURE",
                "name": "ESignature Item",
                "description": null,
                "required": true
            },
            {
                "id": "f43476bf-2e1b-4ca7-8cba-4522ec75321f",
                "type": "QUESTION",
                "name": "Question Item",
                "description": null,
                "required": true
            }
        ],
        "recipients": [
            {
                "first_name": "Pigeon",
                "last_name": "User",
                "email": "support@pigeondocuments.com",
                "phone": "",
                "request_link": null,
                "auth": "NONE"
            }
        ],
        "collaborators": []
    },
    "submission": {
        "recipient": {
            "first_name": "Pigeon",
            "last_name": "User",
            "email": "support@pigeondocuments.com",
            "phone": "",
            "request_link": null,
            "auth": "NONE"
        },
        "status": "PARTIAL",
        "message": "Here's my submission!",
        "submitted_at": "2025-01-01T00:00.00",
        "items": [
            {
                "id": "1a3126ba-9bce-4096-8d73-f2c704837741",
                "type": "STANDARD",
                "name": "Form Item",
                "description": null,
                "required": true
            }
        ]
    }
}

`request.verified`

The request.verified topic is triggered when a requesting users manually validates (accepts) the recipient's submission. The data object in the event payload represents the verified request.

Sample Payload

{
    "event_id": "0b11e21d-85f3-4e30-b3e9-1a260c25070e",
    "topic": "request.verified",
    "organization_id": "0",
    "data": {
        "id": "74e85389-2f99-45ab-8535-b986bedd7759",
        "state": "VERIFIED",
        "owner_id": "0",
        "owner_opened": true,
        "user_opened": true,
        "name": "Updated Request Name",
        "due_date": "2025-01-01T00:00.00",
        "submission_date": "2025-01-01T00:00.00",
        "expiration_date": null,
        "personal_message": null,
        "security_question": null,
        "language": "en-US",
        "reminders": "NONE",
        "items": [
            {
                "id": "1a3126ba-9bce-4096-8d73-f2c704837741",
                "type": "STANDARD",
                "name": "Form Item",
                "description": null,
                "required": true
            },
            {
                "id": "7ad70695-677f-4fd1-92c1-f6c7b3ab132e",
                "type": "E_SIGNATURE",
                "name": "ESignature Item",
                "description": null,
                "required": true
            },
            {
                "id": "f43476bf-2e1b-4ca7-8cba-4522ec75321f",
                "type": "QUESTION",
                "name": "Question Item",
                "description": null,
                "required": true
            }
        ],
        "recipients": [
            {
                "first_name": "Pigeon",
                "last_name": "User",
                "email": "support@pigeondocuments.com",
                "phone": "",
                "request_link": null,
                "auth": "NONE"
            }
        ],
        "collaborators": []
    }
}

`request.rejected`

The request.rejected topic is triggered when a requesting user requests changes to a user's submission. The data object in the event payload represents the rejected request.

The event payload also includes a rejection object that includes details related to the rejection request. This object specifies the following attributes:

Attribute	Type	Description
`message`	`string`	The custom message sent to the request recipient
`keep_original`	`bool`	Indicates if the originally uploaded files were kept (true) or deleted (false)
`items`	`object[]`	Array of items that changes were requested for.
`items.id`	`string`	ID of item.
`items.reason`	`string`	Message describing why the item was rejected and what changes are requested.

Sample Payload

{
    "event_id": "0b11e21d-85f3-4e30-b3e9-1a260c25070e",
    "topic": "request.rejected",
    "organization_id": "0",
    "data": {
        "id": "74e85389-2f99-45ab-8535-b986bedd7759",
        "state": "REJECTED",
        "owner_id": "0",
        "owner_opened": true,
        "user_opened": true,
        "name": "Request Name",
        "due_date": "2025-01-01T00:00.00",
        "submission_date": "2025-01-01T00:00.00",
        "expiration_date": null,
        "personal_message": null,
        "security_question": null,
        "language": "en-US",
        "reminders": "NONE",
        "items": [
            {
                "id": "1a3126ba-9bce-4096-8d73-f2c704837741",
                "type": "STANDARD",
                "name": "Form Item",
                "description": null,
                "required": true
            },
            {
                "id": "7ad70695-677f-4fd1-92c1-f6c7b3ab132e",
                "type": "E_SIGNATURE",
                "name": "ESignature Item",
                "description": null,
                "required": true
            },
            {
                "id": "f43476bf-2e1b-4ca7-8cba-4522ec75321f",
                "type": "QUESTION",
                "name": "Question Item",
                "description": null,
                "required": true
            }
        ],
        "recipients": [
            {
                "first_name": "Pigeon",
                "last_name": "User",
                "email": "support@pigeondocuments.com",
                "phone": "",
                "request_link": null,
                "auth": "NONE"
            }
        ],
        "collaborators": []
    },
    "rejection": {
        "message": "Please fix these items!",
        "keep_original": true,
        "items": [
            {
                "id": "1a3126ba-9bce-4096-8d73-f2c704837741",
                "reason": "Change this!"
            },
            {
                "id": "7ad70695-677f-4fd1-92c1-f6c7b3ab132e",
                "reason": "Change that!"
            }
        ]
    }
}

`request.opened`

The request.opened topic is triggered when a recipient opens a request. It is only fired once per request.

The data object in the event payload represents the opened request. The event payload also includes an opened_by object that specifies the recipient who opened the request.

Sample Payload

{
    "event_id": "0b11e21d-85f3-4e30-b3e9-1a260c25070e",
    "topic": "request.opened",
    "organization_id": "0",
    "data": {
        "id": "74e85389-2f99-45ab-8535-b986bedd7759",
        "state": "INCOMPLETE_AND_LINK_SENT",
        "owner_id": "0",
        "owner_opened": true,
        "user_opened": true,
        "name": "Updated Request Name",
        "due_date": "2025-01-01T00:00.00",
        "submission_date": "2025-01-01T00:00.00",
        "expiration_date": null,
        "personal_message": null,
        "security_question": null,
        "language": "en-US",
        "reminders": "NONE",
        "items": [
            {
                "id": "1a3126ba-9bce-4096-8d73-f2c704837741",
                "type": "STANDARD",
                "name": "Form Item",
                "description": null,
                "required": true
            },
            {
                "id": "7ad70695-677f-4fd1-92c1-f6c7b3ab132e",
                "type": "E_SIGNATURE",
                "name": "ESignature Item",
                "description": null,
                "required": true
            },
            {
                "id": "f43476bf-2e1b-4ca7-8cba-4522ec75321f",
                "type": "QUESTION",
                "name": "Question Item",
                "description": null,
                "required": true
            }
        ],
        "recipients": [
            {
                "first_name": "Pigeon",
                "last_name": "User",
                "email": "support@pigeondocuments.com",
                "phone": "",
                "request_link": null,
                "auth": "NONE"
            }
        ],
        "collaborators": []
    },
    "opened_by": {
        "first_name": "Pigeon",
        "last_name": "User",
        "email": "support@pigeondocuments.com",
        "phone": "",
        "request_link": null,
        "auth": "NONE"
    }
}

`request.reminder`

The request.reminder topic is triggered when a recipient is reminded to complete a request at the configured interval. The data object in the event payload represents the request.

Sample Payload

{
    "event_id": "0b11e21d-85f3-4e30-b3e9-1a260c25070e",
    "topic": "request.reminder",
    "organization_id": "3e02ef23-c6bf-429c-91a9-9a274971076a",
    "data": {
        "id": "74e85389-2f99-45ab-8535-b986bedd7759",
        "state": "INCOMPLETE_AND_LINK_SENT",
        "owner_id": "3441b6f9-d8ed-419c-97f6-7cf8fc53622c",
        "owner_opened": true,
        "user_opened": true,
        "name": "Request w/ Reminders",
        "due_date": "2025-01-01T00:00.00",
        "submission_date": "2025-01-01T00:00.00",
        "expiration_date": null,
        "personal_message": null,
        "security_question": null,
        "language": "en-US",
        "reminders": "DAILY",
        "items": [
            {
                "id": "1a3126ba-9bce-4096-8d73-f2c704837741",
                "type": "STANDARD",
                "name": "Form Item",
                "description": null,
                "required": true
            },
            {
                "id": "7ad70695-677f-4fd1-92c1-f6c7b3ab132e",
                "type": "E_SIGNATURE",
                "name": "ESignature Item",
                "description": null,
                "required": true
            },
            {
                "id": "f43476bf-2e1b-4ca7-8cba-4522ec75321f",
                "type": "QUESTION",
                "name": "Question Item",
                "description": null,
                "required": true
            }
        ],
        "recipients": [
            {
                "first_name": "Pigeon",
                "last_name": "User",
                "email": "support@pigeondocuments.com",
                "phone": "",
                "request_link": null,
                "auth": "NONE"
            }
        ],
        "collaborators": []
    }
}

`item.verified`

The item.verified topic is triggered when a request item is manually verified by a requesting user. The data object in the event payload represents the verified item.

Sample Payload

{
  "event_id": "da74303c-58ce-4c54-ba9e-15814aface35",
  "topic": "item.verified",
  "organization_id": "b3363dd4-7425-41cb-b1dc-9f60b17d6541",
  "data": {
    "name": "Item Name",
    "description": "Item Description",
    "required": true,
    "id": "bcc78608-3b7c-4fa3-aa90-99a305b2e9e2",
    "type": "UPLOAD",
    "request_id": "6cc689d2-f469-4c60-b387-ac3b5aeb04ab"
  }
}

Securing Your Webhooks

It is highly recommended that you secure your integration by verifying that all webhook requests originate from Pigeon. The Pigeon webhook system supports webhook signature validation by providing a unique webhook signature in each webhook request.

Validating Webhook Signatures

Pigeon generates signatures using a hash-based message authentication code (HMAC) with SHA-256. This signature is generated using the webhook signing secret for the specific endpoint and the raw request body, and then included in the X-Signature-SHA256 request header.

You can validate a Pigeon webhook signature via the following steps:

Step 1: Extract the signature from the request header

The signature will be available in the X-Signature-SHA256 header included with the POST request sent to your application.

Step 2: Get your webhook signing secret

Each webhook subscription you create includes a signing_secret value unique to that webhook. The signing_secret value is available in the response to the initial request to create a webhook (POST /webhooks).

The signing_secret is also available via the GET /webhooks/:id/secret route.

Step 3: Compute the expected signature

Compute an HMAC with the SHA256 hash function. Use your webhook signing secret as the key, and use the raw request body (a JSON string) as the message.

Step 4: Compare the signatures

Compare the signature in the header to the expected signature calculated in the previous step. If the signatures match, then the webhook event is valid and can be processed as normal.

Webhooks

Receive Pigeon Webhook Events#

Getting Started#

Webhook Topics#

request.created#

request.updated#

request.deleted#

request.submitted#

request.verified#

request.rejected#

request.opened#

request.reminder#

item.verified#

Securing Your Webhooks#

Validating Webhook Signatures#

Code Samples#

Receive Pigeon Webhook Events

Getting Started

Webhook Topics

`request.created`

`request.updated`

`request.deleted`

`request.submitted`

`request.verified`

`request.rejected`

`request.opened`

`request.reminder`

`item.verified`

Securing Your Webhooks

Validating Webhook Signatures

Code Samples