API docs by Redocly

Webhook interfaces (4.3.0)

Download OpenAPI specification:

Webhook interfaces for postbacks from the Zipit VAS api.

Subscribe to a webook

Request Body schema: application/json
endpointUrl
string <url>

Endpoint which should be posted to when the selected event happens

  • NOTE !!!! We highly recommend ensuring that your webhook endpoint not try to process the message, as messages are posted they should be committed to a message queue and processed from the queue so that processing errors on your side do not cause your endpoint to be disabled
  • If the endpoint returns a 200 response, the post is successful.
  • If an error happens or a non 200 response is received the webhook will be retried for a period of time.
  • After 10 failures, the endpoint will be marked as "failed" in the "status" field.
  • A failed endpoint will still continue to receive events, they will not be posted, but will queue up.
  • A faled endpoint can be restarted
  • After 5 successes, or on manual restart, the failure count will be reset to zero.
eventPatterns
Array of strings (eventTypes)
Items Enum: "*" "billing:*" "billing:chargeDispute" "billing:purchase" "billing:shipment" "billing:subscriptionChange" "billing:subscriptionCycle" "billing:subscriptionEnd" "billing:subscriptionPaymentFailed" "billing:subscriptionStart" "billing:paymentMethodAdded" "billing:paymentMethodUpdated" "claim:claimSuccess" "claim:claimFailure" "claim:unclaimSuccess" "claim:unclaimFailure" "subscription:usage" "device:deviceUpdated" "org:organizationUpdated"

List of event types which should be sent to the specified URL

status
string
Enum: "active" "disabled" "failed"

State of the webhook

  • active - webhook is receiving events
  • disabled - webhook will not receive events, but new events will queue up. This can be used to temporarily "pause" delivery of webhooks.
  • failed - webhook will receive events, but they will not be posted. A webhook endpoint will enter this state when the failure count reaches 10. It can be manually re-enabled by switching the status back to 'active'. Missed webhooks can be manually retried.
id
string

Internal ID of the webhook endpoint.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "endpointUrl": "string",
  • "eventPatterns": [
    ],
  • "status": "active",
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "endpointUrl": "string",
  • "eventPatterns": [
    ],
  • "status": "active",
  • "statusTime": "string",
  • "recentFailureCount": 0,
  • "recentSuccessCount": 0,
  • "id": "string"
}

Callback payload samples

Callback
Content type
application/json
{
  • "eventId": null,
  • "eventDate": null,
  • "customerId": null,
  • "customerName": null,
  • "customerIdentifier": null,
  • "eventType": "billing:subscriptionStart",
  • "body": {
    }
}