Webhooks

Instaply can deliver real-time events to your HTTPS endpoints.

Use the same Instaply API authentication headers (token, Content-Type) as other API calls.

Capabilities

• Create and manage multiple webhooks
• Subscribe to specific event types
• Attach custom headers (for example Authorization) on each delivery

Supported events

Subscribe to one or both:

Event key	Description
messages	A message was sent or received
transfers	A conversation was reassigned to another business

Create webhook

Endpoint: POST https://me.instaply.com/api/webhooks/

Request body:

{
  "url": "https://example.com/webhook",
  "enabled": true,
  "subscribedEvents": ["messages", "transfers"],
  "extraHeaders": [
    {
      "name": "Authorization",
      "value": "Bearer your-secret"
    }
  ]
}

Fields

Field	Required	Description
url	yes	HTTPS URL that receives webhook POST deliveries
enabled	no	Default true
subscribedEvents	yes	Array of messages and/or transfers
extraHeaders	no	Objects with name and value; sent on every delivery

List webhooks

Return all webhooks for your organization, or fetch one by ID.

Endpoints:

• GET https://me.instaply.com/api/webhooks/
• GET https://me.instaply.com/api/webhooks/:webHookId

Update webhook

Endpoint: POST https://me.instaply.com/api/webhooks/:webHookId/update

Request body (all fields optional; provided fields are updated):

{
  "url": "https://example.com/new-webhook",
  "enabled": false,
  "subscribedEvents": ["messages"],
  "extraHeaders": [
    {
      "name": "Authorization",
      "value": "Bearer updated-secret"
    }
  ]
}

Delete webhook

Endpoint: POST https://me.instaply.com/api/webhooks/:webHookId/delete

Delivery

When an event occurs, Instaply sends an HTTP POST to your configured URL.

Message event payload

Triggered when a message is sent or received.

{
  "eventType": "message",
  "timestamp": 1700000000000,
  "data": {
    "fromCustomer": true,
    "invisible": false,
    "customerThreadId": 123456,
    "businessId": 1001,
    "organizationId": 200,
    "customerId": "cust_001",
    "customerType": "prospect",
    "messageId": 555001,
    "messageBody": "Hello",
    "messageTimestamp": 1700000000000,
    "messageAttachmentUUID": null,
    "messageAttachmentContentType": null,
    "messageAttachmentName": null,
    "messageAttachmentContentLength": null,
    "channel": "webchat"
  }
}

Transfer event payload

Triggered when a conversation is transferred from one business to another.

{
  "eventType": "transfer",
  "timestamp": 1700000000000,
  "data": {
    "customerThreadId": "123456",
    "organizationId": 200,
    "previousBusinessId": 1001,
    "newBusinessId": 2002,
    "newBusinessName": "Support Team",
    "employeeUserId": 7890,
    "businessParticipationId": 456789,
    "customerChannel": "EMAIL"
  }
}

Legacy delivery payload

Legacy webhooks only receive message events. Payload shape:

{
  "customerId": "cust_001",
  "customerThreadId": 123456,
  "messageTimestamp": 1700000000000,
  "employeeUserId": 1001,
  "messageId": 555001,
  "messageBody": "Hello, I would like more information.",
  "businessId": 2001,
  "messageAttachmentName": null,
  "messageAttachmentContentType": null,
  "messageAttachmentUUID": null,
  "messageAttachmentContentLength": null,
  "fromCustomer": false,
  "messageExternalId": null,
  "invisible": false,
  "customerType": "prospect"
}