Create a webhook.

POST

/webhooks

curl --request POST \
  --url https://api.pingram.io/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "webhook": "example", "events": [ "EMAIL_OPEN" ] }'

• Production

Authorizations

• apiKey
• clientCredentials
• endUser
• endUserHashed

Request Body^required

Media typeapplication/json

Request body for creating or updating an events webhook endpoint.

object

webhook

required

Destination URL that receives webhook event payloads. Must be a valid http(s) URL.

string

events

required

List of event types that should be forwarded to the webhook URL.

Array<string>

Allowed values: EMAIL_OPEN EMAIL_CLICK EMAIL_FAILED EMAIL_DELIVERED EMAIL_UNSUBSCRIBE EMAIL_INBOUND INAPP_WEB_FAILED INAPP_WEB_UNSUBSCRIBE SMS_DELIVERED SMS_FAILED SMS_UNSUBSCRIBE SMS_SUBSCRIBE SMS_INBOUND PUSH_FAILED PUSH_UNSUBSCRIBE CALL_FAILED CALL_UNSUBSCRIBE WEB_PUSH_FAILED WEB_PUSH_UNSUBSCRIBE SLACK_FAILED SLACK_UNSUBSCRIBE

Responses

200

Successful response

Media typeapplication/json

Destination URL that receives signed event payloads for a set of subscribed events.

object

id

required

Unique identifier for this endpoint within the account.

string

webhook

required

Destination URL that receives webhook event payloads.

string

events

required

List of subscribed event types for this endpoint.

Array<string>

Allowed values: EMAIL_OPEN EMAIL_CLICK EMAIL_FAILED EMAIL_DELIVERED EMAIL_UNSUBSCRIBE EMAIL_INBOUND INAPP_WEB_FAILED INAPP_WEB_UNSUBSCRIBE SMS_DELIVERED SMS_FAILED SMS_UNSUBSCRIBE SMS_SUBSCRIBE SMS_INBOUND PUSH_FAILED PUSH_UNSUBSCRIBE CALL_FAILED CALL_UNSUBSCRIBE WEB_PUSH_FAILED WEB_PUSH_UNSUBSCRIBE SLACK_FAILED SLACK_UNSUBSCRIBE

secret

required

HMAC secret for verifying webhook signatures. Use this with your X-Pingram-Signature verification.

string

Example

{
  "events": [
    "EMAIL_OPEN"
  ]
}

400

Bad Request - validation errors, invalid input

Media typeapplication/json

Standard error response for API errors.

object

trackingId

required

Unique tracking ID for the request.

string

error

required

Structured error details for API error responses.

object

code

required

Machine-readable error code.

string

message

required

Human-readable error message.

string

fix

Actionable hint for fixing the error.

string

Example^generated

{
  "trackingId": "example",
  "error": {
    "code": "example",
    "message": "example",
    "fix": "example"
  }
}

401

Unauthorized

402

Payment Required - usage limits exceeded

Media typeapplication/json

Standard error response for API errors.

object

trackingId

required

Unique tracking ID for the request.

string

error

required

Structured error details for API error responses.

object

code

required

Machine-readable error code.

string

message

required

Human-readable error message.

string

fix

Actionable hint for fixing the error.

string

Example^generated

{
  "trackingId": "example",
  "error": {
    "code": "example",
    "message": "example",
    "fix": "example"
  }
}

500

Internal Server Error

502

Bad Gateway - provider error

Media typeapplication/json

Standard error response for API errors.

object

trackingId

required

Unique tracking ID for the request.

string

error

required

Structured error details for API error responses.

object

code

required

Machine-readable error code.

string

message

required

Human-readable error message.

string

fix

Actionable hint for fixing the error.

string

Example^generated

{
  "trackingId": "example",
  "error": {
    "code": "example",
    "message": "example",
    "fix": "example"
  }
}