Get started

Webhook Events

PostPulse sends webhook events to notify your application about important changes in media imports and posting operations. Configure webhook endpoints at https://post-pulse.com/app/portal/webhooks to receive real-time notifications.

Webhook Reference

Overview

Webhooks are HTTP POST requests sent to your configured endpoints when specific events occur. Each webhook contains a JSON payload with event details and metadata.

Event Structure: All webhook events follow a common structure with id, type, occurredAt, and data fields.

Common Event Structure

{
  "id": "unique-event-id",
  "type": "event.type.name",
  "occurredAt": "2024-01-15T10:30:00",
  "data": {
    // Event-specific payload
  }
}

Media Import Events

Events related to media file import and processing operations.

media.import.queued

Triggered when a media import task is created and queued for processing.

Data Fields

FieldTypeDescription
taskIdstringUnique identifier for the import task
statestringCurrent state: QUEUED, DOWNLOADING, VALIDATING, UPLOADING, READY, FAILED_TEMPORARY, FAILED_PERMANENT
sourceUrlstringURL of the media file being imported

Example Payload

{
  "id": "evt_123456789",
  "type": "media.import.queued",
  "occurredAt": "2024-01-15T10:30:00",
  "data": {
    "taskId": "12345",
    "state": "QUEUED",
    "sourceUrl": "https://example.com/video.mp4"
  }
}

media.import.progress

Triggered during media import processing to report progress updates.

Data Fields

FieldTypeDescription
taskIdstringUnique identifier for the import task
statestringCurrent state: DOWNLOADING, VALIDATING, UPLOADING
bytesDownloadednumberNumber of bytes downloaded so far
totalBytesnumberTotal file size in bytes (-1 if unknown)
detectedMimestringDetected MIME type of the file

Example Payload

{
  "id": "evt_123456790",
  "type": "media.import.progress",
  "occurredAt": "2024-01-15T10:30:15",
  "data": {
    "taskId": "12345",
    "state": "DOWNLOADING",
    "bytesDownloaded": 1048576,
    "totalBytes": 5242880,
    "detectedMime": "video/mp4"
  }
}

media.import.ready

Triggered when media import completes successfully.

Data Fields

FieldTypeDescription
taskIdstringUnique identifier for the import task
statestringFinal state of the task ("READY")
s3KeystringS3 key where the imported file is stored
detectedMimestringDetected MIME type of the file
bytesDownloadednumberTotal bytes downloaded

Example Payload

{
  "id": "evt_123456791",
  "type": "media.import.ready",
  "occurredAt": "2024-01-15T10:31:00",
  "data": {
    "taskId": "12345",
    "state": "READY",
    "s3Key": "media/user123/video_12345.mp4",
    "detectedMime": "video/mp4",
    "bytesDownloaded": 5242880
  }
}

media.import.failed.temporary

Triggered when media import fails temporarily and will be retried.

Data Fields

FieldTypeDescription
taskIdstringUnique identifier for the import task
statestringCurrent state ("FAILED_TEMPORARY")
attemptsnumberNumber of retry attempts made
errorCodestringError code identifying the failure type
errorMessagestringHuman-readable error description

Example Payload

{
  "id": "evt_123456792",
  "type": "media.import.failed.temporary",
  "occurredAt": "2024-01-15T10:30:45",
  "data": {
    "taskId": "12345",
    "state": "FAILED_TEMPORARY",
    "attempts": 2,
    "errorCode": "TIMEOUT",
    "errorMessage": "Connection timeout while downloading media"
  }
}

media.import.failed.permanent

Triggered when media import fails permanently and will not be retried.

Data Fields

FieldTypeDescription
taskIdstringUnique identifier for the import task
statestringFinal state ("FAILED_PERMANENT")
attemptsnumberTotal number of attempts made
errorCodestringError code identifying the failure type
errorMessagestringHuman-readable error description

Example Payload

{
  "id": "evt_123456793",
  "type": "media.import.failed.permanent",
  "occurredAt": "2024-01-15T10:35:00",
  "data": {
    "taskId": "12345",
    "state": "FAILED_PERMANENT",
    "attempts": 5,
    "errorCode": "UNSUPPORTED_MIME",
    "errorMessage": "File format not supported"
  }
}

Posting Events

Events related to social media posting operations and their lifecycle.

Post Events

post.completed

Triggered when an individual post to a social media platform completes successfully.

  • scheduleId:
  • publicationId:
  • postId:
  • status: COMPLETED
  • platform:
  • accountId:
  • platformPostIdentifier:

post.failed

Triggered when an individual post to a social media platform fails.

  • scheduleId:
  • publicationId:
  • postId:
  • status: FAILED
  • platform:
  • accountId:
  • errorMessage:

Post Event Example

{
  "id": "evt_post_123",
  "type": "post.completed",
  "occurredAt": "2024-01-15T14:30:00",
  "data": {
    "scheduleId": "schedule_456",
    "publicationId": "pub_789",
    "postId": "post_101112",
    "status": "COMPLETED",
    "platform": "TWITTER",
    "accountId": "acc_twitter_123",
    "platformPostIdentifier": "1234567890123456789",
    "errorMessage": null
  }
}

Publication Events

publication.completed

Triggered when all posts in a platform publication complete successfully.

publication.failed

Triggered when all posts in a platform publication fail.

publication.partially_completed

Triggered when some posts in a platform publication succeed while others fail.

Schedule Events

schedule.completed

Triggered when all publications in a posting schedule complete successfully.

schedule.failed

Triggered when all publications in a posting schedule fail.

schedule.partially_completed

Triggered when some publications in a posting schedule succeed while others fail.

Schedule Event Example

{
  "id": "evt_schedule_126",
  "type": "schedule.completed",
  "occurredAt": "2024-01-15T15:00:00",
  "data": {
    "scheduleId": "schedule_456",
    "status": "COMPLETED"
  }
}

Media Import Error Codes

When media import events fail, they include specific error codes to help you understand and handle different failure scenarios.

Permanent Failure Codes

These errors indicate permanent failures that will not be retried:

Error CodeDescriptionResolution
UNSUPPORTED_MIMEFile extension is not supported or file is not image/videoUse supported image or video formats only
FILE_TOO_LARGEFile exceeds the size limit for its typeReduce file size or use a smaller file
SECURITYSecurity validation failedEnsure the file and source URL are safe
SOURCE_ERRORHTTP 4xx error from source host or too many redirectsCheck source URL accessibility and redirect chains

Temporary Failure Codes

These errors indicate temporary failures that will be automatically retried:

Error CodeDescriptionResolution
TIMEOUTSocket timeout during downloadWait for automatic retry or check network connectivity
UNEXPECTEDUnexpected error during processingWait for automatic retry or contact support if persistent
Retry Behavior: Temporary failures are automatically retried with exponential backoff. The system will attempt up to 5 retries before marking the task as permanently failed.

Webhook Configuration

Configure webhook endpoints at PostPulse Developer Portal to receive these events. You can filter which event types you want to receive for each endpoint.

Security: All webhook requests include authentication headers to verify the request origin. Always validate webhook signatures before processing events in your application.
Retry Policy: Failed webhook deliveries are automatically retried with exponential backoff. Ensure your endpoint returns appropriate HTTP status codes (2xx for success, 4xx for permanent failures, 5xx for temporary failures).

Webhook Headers

Content-Type: application/json
User-Agent: PostPulse-Webhooks/1.0
X-PostPulse-Event: event.type.name
X-PostPulse-Signature: sha256=signature_hash

Event Types Summary

CategoryEvent TypesCount
Media Importqueued, progress, ready, failed.temporary, failed.permanent5
Post Eventscompleted, failed2
Publication Eventscompleted, failed, partially_completed3
Schedule Eventscompleted, failed, partially_completed3
TotalAll webhook event types13