Skip to content

Replace one webhook endpoint's URL and its full event subscription. endpointId comes from list or create. The signing secret stays the same. events is the complete set; omitting an event unsubscribes it. The URL must be a public HTTPS URL.

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

Authorizations

Parameters

Path Parameters

endpointId
required
string

Id of the webhook endpoint, from list or create.

Request Bodyrequired

Media typeapplication/json

Request body for creating or updating an events webhook endpoint.

object
webhook
required

Public HTTPS URL that accepts POST with a JSON event body. Return 2xx to acknowledge. Private, loopback, and link-local addresses are rejected. Requests include X-Pingram-Id, X-Pingram-Signature (v1 HMAC-SHA256), and X-Pingram-Timestamp.

string
events
required

Full set of event types to deliver to this URL. Omitting an event on update unsubscribes it. Inbound SMS to the free shared number only works when that person has already received a text from this number. Inbound SMS to a dedicated number works normally.

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 ACCOUNT_USAGE

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 signed JSON event payloads.

string
events
required

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 ACCOUNT_USAGE
secret
required

HMAC secret for verifying X-Pingram-Signature. Returned on create and list; updates keep the same secret. Format: pingram_whsecret_…

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
Examplegenerated
{
  "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
Examplegenerated
{
  "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
Examplegenerated
{
  "trackingId": "example",
  "error": {
    "code": "example",
    "message": "example",
    "fix": "example"
  }
}