Webhooks

Subscribe to real-time events in your Oktopost account and receive instant notifications via HTTP callbacks.

Webhooks enable you to build integrations that subscribe to events happening in your Oktopost account. When an event occurs, Oktopost sends an HTTP POST request to the URL you specify, allowing you to trigger automated workflows, sync data to external systems, or build custom notifications.

How Webhooks Work

Create a webhook - Specify which event to monitor and where to send notifications
Event occurs - When the subscribed event happens in Oktopost, a webhook is triggered
Receive notification - Oktopost sends an HTTP POST request to your endpoint with event details
Process the event - Your application receives and processes the webhook payload

Webhooks are sent in real-time as events occur. For event history and debugging, use the Webhook Log endpoint to review past webhook executions.

Supported Events

You can subscribe to the following event types when creating or updating webhooks:

Advocacy Events

Event Type	Description
newAdvocacyMessage	Triggers when a new message is added to the advocacy board
newAdvocacyStory	Triggers when a new story is added to the advocacy board
newAdvocacyTopic	Triggers when a new topic is added to the advocacy board

Publishing Events

Event Type	Description
postCreated	Triggers when a user creates a new post
postModified	Triggers when a user updates a scheduled post
postDeleted	Triggers when a user deletes a scheduled post
postSent	Triggers when a post is published to social media

Engagement Events

Event Type	Description
newConversation	Triggers when a new conversation appears in your inbox
conversationUpdated	Triggers when new comments or replies are added to an existing conversation
conversationStatusUpdated	Triggers when a conversation status changes
newNoteOnConversation	Triggers when a note is added to a conversation
newAssignment	Triggers when a conversation is assigned to a user

Lead & Conversion Events

Event Type	Description
newLead	Triggers when a new lead is captured
newLeadActivity	Triggers when new social activity is detected for a lead
newConversion	Triggers when a social conversion is captured

Workflow Events

Event Type	Description
newApprovalItem	Triggers when posts or messages are sent to approval
approvalItemApproved	Triggers when posts or messages are approved
approvalItemRejected	Triggers when posts or messages are rejected

Other Events

Event Type	Description
newCampaign	Triggers when a new campaign is created

List Webhooks

Retrieve all webhooks configured in your account with optional filtering and pagination.

Parameters

Parameter	Type	Required	Description
event	String	No	Filter by event type. See supported events above.
name	String	No	Search webhooks by name
_order	String	No	Sort order. Options: `name`, `description`, `lastExecutionDate`, `isEnabled`, `created`, `modified`. Default: `name`
_page	Integer	No	Page number for pagination. Default: `0`
_count	Integer	No	Items per page. Options: `20`, `25`, `50`, `100`. Default: `20`

Request

curl -u ACCOUNT_ID:API_KEY \
  "https://api.oktopost.com/v2/webhook"

Response

{
	"Result": true,
	"Items": [
		{
			"Id": "0WA000000000001",
			"Name": "My Webhook",
			"Description": "Send new assignment to Slack",
			"Event": "newAssignment",
			"Url": "https://hooks.slack.com/services/...",
			"LastExecutionDate": "2024-01-15 10:30:00",
			"IsEnabled": 1,
			"Created": "2017-05-23 14:07:18",
			"Modified": "2017-05-23 14:07:18"
		}
	],
	"Total": 1
}

Get Webhook

Retrieve details for a specific webhook by ID.

Request

curl -u ACCOUNT_ID:API_KEY \
  https://api.oktopost.com/v2/webhook/0WA000000000001

Response

{
	"Result": true,
	"Webhook": {
		"Id": "0WA000000000001",
		"Name": "My Webhook",
		"Description": "Send new assignment to Slack",
		"Event": "newAssignment",
		"Url": "https://hooks.slack.com/services/...",
		"LastExecutionDate": "2024-01-15 10:30:00",
		"IsEnabled": 1,
		"Created": "2017-05-23 14:07:18",
		"Modified": "2017-05-23 14:07:18"
	}
}

Create Webhook

Create a new webhook to subscribe to a specific event type.

Parameters

Parameter	Type	Required	Description
event	String	Yes	The event type to subscribe to. See supported events above.
name	String	Yes	A descriptive name for this webhook
url	String	Yes	The endpoint URL where webhook payloads will be sent
description	String	No	Additional details about this webhook's purpose
isEnabled	Integer	No	Enable or disable the webhook. `1` = enabled, `0` = disabled. Default: `1`

Request

curl -u ACCOUNT_ID:API_KEY \
  https://api.oktopost.com/v2/webhook -X POST \
  -d event="newAssignment" \
  -d name="Slack Assignment Notification" \
  -d description="Send assignment notifications to Slack" \
  -d url="https://hooks.slack.com/services/..." \
  -d isEnabled=1

Response

{
	"Result": true,
	"Webhook": {
		"Id": "0WA000000000001",
		"Name": "Slack Assignment Notification",
		"Description": "Send assignment notifications to Slack",
		"Event": "newAssignment",
		"Url": "https://hooks.slack.com/services/...",
		"LastExecutionDate": "-",
		"IsEnabled": 1,
		"Secret": "a1b2c3d4e5f6...",
		"Created": "2017-05-23 14:07:18",
		"Modified": "2017-05-23 14:07:18"
	}
}

When creating a webhook, a Secret is generated. Use this secret to verify that webhook requests are genuinely from Oktopost (see Security section below).

Update Webhook

Modify an existing webhook's configuration.

Parameters

Parameter	Type	Required	Description
event	String	No	Change the event type this webhook subscribes to
name	String	No	Update the webhook name
url	String	No	Update the destination URL
description	String	No	Update the description
isEnabled	Integer	No	Enable or disable the webhook. `1` = enabled, `0` = disabled

Request

curl -u ACCOUNT_ID:API_KEY \
  https://api.oktopost.com/v2/webhook/0WA000000000001 -X POST \
  -d name="Updated Webhook Name" \
  -d description="Updated description" \
  -d isEnabled=0

Response

{
	"Result": true,
	"Webhook": {
		"Id": "0WA000000000001",
		"Name": "Updated Webhook Name",
		"Description": "Updated description",
		"Event": "newAssignment",
		"Url": "https://hooks.slack.com/services/...",
		"LastExecutionDate": "2024-01-15 10:30:00",
		"IsEnabled": 0,
		"Created": "2017-05-23 14:07:18",
		"Modified": "2024-01-16 09:15:32"
	}
}

Delete Webhook

Remove a webhook. This action cannot be undone.

Request

curl -u ACCOUNT_ID:API_KEY \
  https://api.oktopost.com/v2/webhook/0WA000000000001 -X DELETE

Response

{
	"Result": true
}

Webhook Log

View the execution history for a specific webhook, including response codes, execution times, and payloads sent.

Request

curl -u ACCOUNT_ID:API_KEY \
  https://api.oktopost.com/v2/webhook-log/0WA000000000001

Response

{
	"Result": true,
	"Items": [
		{
			"Id": "0WC000000000001",
			"WebhookPayloadId": "0WB000000000001",
			"Created": "2017-05-23 14:07:18",
			"ResponseCode": 200,
			"ExecutionTime": 0.034530,
			"Payload": {
				"event": "newAssignment",
				"data": {
					"conversationId": "123456",
					"assignedTo": "user@example.com",
					"assignedBy": "manager@example.com"
				}
			}
		}
	],
	"Total": 1
}

Response Fields

Field	Description
ResponseCode	HTTP status code returned by your webhook endpoint
ExecutionTime	Time in seconds it took your endpoint to respond
Payload	The complete webhook payload that was sent to your endpoint

Use webhook logs to:

Debug webhook delivery issues
Monitor webhook performance
Review historical event data
Verify payload structures

Webhook Payload Structure

When an event occurs, Oktopost sends a POST request to your webhook URL with the following structure:

{
	"event": "newAssignment",
	"timestamp": 1705315200,
	"webhookId": "0WA000000000001",
	"data": {
		// Event-specific data
	}
}

The data object contains information specific to the event type. For example:

newAssignment Event:

{
	"event": "newAssignment",
	"timestamp": 1705315200,
	"webhookId": "0WA000000000001",
	"data": {
		"conversationId": "123456",
		"assignedTo": "user@example.com",
		"assignedBy": "manager@example.com",
		"assignedAt": "2024-01-15 10:30:00"
	}
}

postSent Event:

{
	"event": "postSent",
	"timestamp": 1705315200,
	"webhookId": "0WA000000000001",
	"data": {
		"postId": "0PL000000000001",
		"network": "LinkedIn",
		"campaignId": "002000000000001",
		"sentAt": "2024-01-15 10:30:00"
	}
}

Security Best Practices

Verify Webhook Signatures

Use the webhook Secret to verify that requests are genuinely from Oktopost:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return signature === expectedSignature;
}

Endpoint Requirements

Your webhook endpoint should:

Respond quickly - Return a 2xx status code within 5 seconds
Use HTTPS - All webhook URLs must use HTTPS
Handle retries - Oktopost retries failed webhooks up to 3 times
Be idempotent - Handle duplicate webhook deliveries gracefully
Validate payloads - Always verify the webhook secret before processing

Error Handling

If your endpoint returns a non-2xx status code or times out:

Oktopost will retry the webhook up to 3 times
Retries use exponential backoff (5s, 25s, 125s)
After 3 failed attempts, the webhook delivery is abandoned
Check the webhook log to diagnose delivery issues

Set up an endpoint - Create a publicly accessible HTTPS endpoint to receive webhooks
Create a webhook - Use the API to create a webhook pointing to your endpoint
Test the webhook - Trigger the subscribed event in Oktopost to test delivery
Verify signatures - Implement signature verification for security
Handle errors - Add error handling and logging to your webhook handler
Monitor logs - Use the webhook log endpoint to monitor delivery and troubleshoot issues

For questions or assistance with webhook implementation, please contact our support team.

On this page