Webhooks allow you to get notified about events happening in your Plain workspace. You can react to these events in many ways, such as:
- Assigning customers to users based on business requirements (urgency, customer value, recurrency, etc.)
- Creating an AI-powered auto-responder
- Creating issues for customers based on their messages
- Triggering internal incidents (by identifying patterns in inbound messages)
- Tracking metrics from your customer support team
Plain events are delivered as Webhook requests.
In order to receive webhook requests, you need a publicly available HTTPS endpoint. Plain will make
HTTP POST request to this endpoint whenever an event you are interested in occurs.
Once your endpoint is ready, you may create a webhook target in Plain. A webhook target tells Plain what events you are interested in and where to send those events.
You can create it by going to Settings → Webhooks, then clicking on 'Add webhook target'
Then, you need to choose a name (e.g. 'Customer notifications'), the URL of your webhook endpoint, the events you want to receive and whether you want to enable it straight away.
You can create up to 25 webhook targets per workspace.
Plain events may contain Personally Identifiable Information (PII). If you want to test webhooks with a production workspace, take the necessary precautions to avoid leaking PII to untrusted parties.
We have created a repository where you will find instructions on how to create a webhook endpoint using different programming languages. You can find it here (opens in a new tab).
Webhook requests are always sent through HTTPS.
If you want you can include authentication credentials in the URL (
https://username:firstname.lastname@example.org) which will then be sent along the webhook request in an
Authorization: Basic cGxhaW46cm9ja3M=
Plain guarantees at-least-once delivery of webhook requests. As such, you should make sure your webhook endpoint is idempotent. The
id field in the webhook request body can be used as an idempotency key.
Plain considers a webhook request to be successfully delivered if your endpoint returns a 2xx HTTP status code. The contents of the response body are ignored.
Any other HTTP status code will be considered a failure, including redirects, which are explicitly forbidden.
When a webhook request fails, Plain will keep retrying it during the ~5 days after the first request. The delay between retries is set by the following table:
|Retry #||Delay||Approximate time since first attempt|
Plain keeps track of all the webhook delivery attempts and their results. Each webhook request includes some metadata that you can use in order to know which delivery attempt it is currently being processed.
Webhook requests are sent as an
HTTP POST request to the webhook target URL.
User-Agent: Plain-Webhooks/1.0 (plain.com; email@example.com)`
Plain-Workspace-Id: The ID of the workspace where the Plain event originated
Plain-Webhook-Target-Id: The ID of the webhook target this webhook request is being sent to
Plain-Webhook-Delivery-Attempt-Id: The ID of the delivery attempt. It will be different on every delivery attempt
Plain-Webhook-Delivery-Attempt-Number: The current delivery attempt number (starts at 1)
Plain-Webhook-Delivery-Attempt-Timestamp: The time at which the delivery attempt was made. In UTC and formatted as ISO8601. E.g.
Plain-Event-Type: The Plain event's type
Plain-Event-Id: The ID of the Plain event. It remains the same across all of the delivery attempts
Authorization header is sent if the webhook target URL contains authentication credentials.
The request body is a
JSON object with the fields below.
The JSON schema for Plain the webhook request body can be found here (opens in a new tab).
If you prefer, you can browse the schema using this interactive tool (opens in a new tab).
|The ID of the Plain event. It remains the same across all of the delivery attempts|
|The Plain event's type|
|Metadata associated with the webhook request. See Webhook Metadata for more details|
|The Plain event's timestamp. In UTC and formatted as ISO8601. E.g. |
|The ID of the workspace where the Plain event originated|
|The Plain event's payload (Example);|
All the following fields are also sent as HTTP headers.
|The ID of the webhook target this webhook request is being sent to. This is the ID that you will find under Settings -> Webhooks in the Support App|
|The ID of the delivery attempt. It will be different on every delivery attempt|
|The current delivery attempt number (starts at 1)|
|The time at which the delivery attempt was made. In UTC and formatted as ISO8601. E.g. |