Create or update the events webhook configuration for the current account/environment.

PUT

/webhooks/events

curl --request PUT \
  --url https://api.pingram.io/webhooks/events \
  --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 the events webhook configuration.

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 VOICE_INBOUND

Responses

200

Successful response

Media typeapplication/json

Events webhook configuration returned by the API.

object

webhookId

required

Storage key in the format accountId:envId (currently accountId:accountId for account-scoped usage).

string

webhook

required

Destination URL that receives webhook event payloads.

string

events

required

List of subscribed event types for this webhook configuration.

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 VOICE_INBOUND

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"
  }
}