/webhooks

Use this resource to view and create new webhooks. Webhooks consist of the event type that the webhook should execute on, and the URL that TMS will POST to when the webhook executes.

TMS will POST data to the URL you provide using the application/x-www-form-urlencoded Content-Type. Below is an example of the payload that TMS will POST:

  completed_at=2015-08-05+18%3A47%3A18+UTC&message_type=sms&message_url=https%3A%2F%2Ftms.govdelivery.com%2Fmessages%2Fsms%2F295117&recipient_url=https%3A%2F%2Ftms.govdelivery.com%2Fmessages%2Fsms%2F295117%2Frecipients%2F373810&sid=e6c48d6d2e4ad639ac4ef6cadd386ed7&status=sent
Secured By: Authentication Token
Description:

Lists your webhooks

Responses with more than 50 records will be paginated to 50 records per response, unless otherwise specified.

Headers

Name Required Type Description
X-AUTH-TOKEN * string

An authentication token provided to you by GovDelivery.

Status

Headers

Name Type Description
Link string

Appropriate pagination link relations. Can include “first”, “last”, “prev”, and “next” relations.

Example

< /webhooks?page=1>; rel="first",
< /webhooks?page=2>; rel="prev",
< /webhooks?page=4>; rel="next",
< /webhooks?page=5>; rel="last"

Body

Format: application/json

Example
[
  {
    "url": "http://youragencysite.com/api/message_events",
    "event_type": "failed",
    "created_at": "2015-04-10T19:12:31Z",
    "_links": {
      "self": "/webhooks/21768"
    }
  },
  {
    "url": "http://youragencysite.com/api/message_events",
    "event_type": "sent",
    "created_at": "2015-02-02T18:55:15Z",
    "_links": {
      "self": "/webhooks/18949"
    }
  }
]
Schema
Array of objects that may include:
Name Type Description
url string

The URL that the webhook will POST to when it executes.

Example

http://youragencysite.com/api/message_events
event_type string

The type of message delivery event the webhook will execute on. Each event represents the state that a specific recipient has entered (e.g. the ‘failed’ event_type indicates that the recipient has entered the ‘failed’ state).

  • sending: TMS is attempting to send the message to the recipient.
  • sent: TMS has successfully delivered the message to the recipient.
  • blacklisted: The recipient is on the delivery blacklist, thus the message was not delivered to the recipient.
  • canceled: Delivery of this message was canceled, thus the message was not delivered to the recipient.
  • failed: TMS encountered an error while attempting to deliver the message to the recipeint.
  • inconclusive: TMS has attempted to deliver the message to the recipient, but has not received notification of a successful nor failed delivery.

Valid Values:

  • sending
  • sent
  • canceled
  • blacklisted
  • failed
  • inconclusive

Example

sent
created_at string

The date and time when the webhook was created.

Example

2015-04-10T19:12:31Z
_links object

An object that defines links to related objects.

Properties

{
  "self": {
    "description": "Relative URI of the object",
    "type": "string",
    "example": "/webhooks/10040"
  }
}
 
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Webhooks",
  "description": "Create a new webhook to have TMS execute while delivering a message.",
  "type": "array",
  "items": {
    "title": "Webhook",
    "type": "object",
    "properties": {
      "url": {
        "description": "The URL that the webhook will POST to when it executes.\n",
        "type": "string",
        "example": "http://youragencysite.com/api/message_events"
      },
      "event_type": {
        "description": "The type of message delivery event the webhook will execute on.\nEach event represents the state that a specific recipient has \nentered (e.g. the 'failed' event_type indicates that the recipient\nhas entered the 'failed' state).\n\n- sending: TMS is attempting to send the message to the recipient.\n- sent: TMS has successfully delivered the message to the recipient.\n- blacklisted: The recipient is on the delivery blacklist, thus the \n    message was not delivered to the recipient.\n- canceled: Delivery of this message was canceled, thus the message\n    was not delivered to the recipient.\n- failed: TMS encountered an error while attempting to deliver the\n    message to the recipeint.\n- inconclusive: TMS has attempted to deliver the message to the\n    recipient, but has not received notification of a successful \n    nor failed delivery.\n",
        "type": "string",
        "enum": [
          "sending",
          "sent",
          "canceled",
          "blacklisted",
          "failed",
          "inconclusive"
        ],
        "example": "sent"
      },
      "created_at": {
        "description": "The date and time when the webhook was created.",
        "type": "string",
        "example": "2015-04-10T19:12:31Z"
      },
      "_links": {
        "title": "Relational Links",
        "description": "An object that defines links to related objects.",
        "type": "object",
        "properties": {
          "self": {
            "description": "Relative URI of the object",
            "type": "string",
            "example": "/webhooks/10040"
          }
        }
      }
    }
  }
}

Body

Format: application/json

Example
{
  "error": "Invalid authentication token"
}
Secured By: Authentication Token
Description:

Create a new webhook to have TMS execute while delivering a message.

Headers

Name Required Type Description
X-AUTH-TOKEN * string

An authentication token provided to you by GovDelivery.

Body

Format: application/json

Example
{
  "url": "http://youragencysite.com/api/message_events",
  "event_type": "failed"
}
Schema
Object that may include:
Name Required Type Description
url * string

The URL that the webhook will POST to when it executes.

Example

http://youragencysite.com/api/message_events
event_type * string

The type of message delivery event the webhook will execute on. Each event represents the state that a specific recipient has entered (e.g. the ‘failed’ event_type indicates that the recipient has entered the ‘failed’ state).

  • sending: TMS is attempting to send the message to the recipient.
  • sent: TMS has successfully delivered the message to the recipient.
  • blacklisted: The recipient is on the delivery blacklist, thus the message was not delivered to the recipient.
  • canceled: Delivery of this message was canceled, thus the message was not delivered to the recipient.
  • failed: TMS encountered an error while attempting to deliver the message to the recipeint.
  • inconclusive: TMS has attempted to deliver the message to the recipient, but has not received notification of a successful nor failed delivery.

Valid Values:

  • sending
  • sent
  • canceled
  • blacklisted
  • failed
  • inconclusive

Example

sent
 
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "/webhooks",
  "description": "Create a new webhook to have TMS execute while delivering a message.\n",
  "type": "object",
  "properties": {
    "url": {
      "description": "The URL that the webhook will POST to when it executes.\n",
      "type": "string",
      "example": "http://youragencysite.com/api/message_events"
    },
    "event_type": {
      "description": "The type of message delivery event the webhook will execute on.\nEach event represents the state that a specific recipient has \nentered (e.g. the 'failed' event_type indicates that the recipient\nhas entered the 'failed' state).\n\n- sending: TMS is attempting to send the message to the recipient.\n- sent: TMS has successfully delivered the message to the recipient.\n- blacklisted: The recipient is on the delivery blacklist, thus the \n    message was not delivered to the recipient.\n- canceled: Delivery of this message was canceled, thus the message\n    was not delivered to the recipient.\n- failed: TMS encountered an error while attempting to deliver the\n    message to the recipeint.\n- inconclusive: TMS has attempted to deliver the message to the\n    recipient, but has not received notification of a successful \n    nor failed delivery.\n",
      "type": "string",
      "enum": [
        "sending",
        "sent",
        "canceled",
        "blacklisted",
        "failed",
        "inconclusive"
      ],
      "example": "sent"
    }
  },
  "required": [
    "url",
    "event_type"
  ]
}
Form Parameters
Name Required Type Description
url * string

The URL that the webhook will POST to when it executes.

Example

http://youragencysite.com/api/message_events
event_type * string

The type of message delivery event the webhook will execute on. Each event represents the state that a specific recipient has entered (e.g. the ‘failed’ event_type indicates that the recipient has entered the ‘failed’ state).

  • sending: TMS is attempting to send the message to the recipient.
  • sent: TMS has successfully delivered the message to the recipient.
  • blacklisted: The recipient is on the delivery blacklist, thus the message was not delivered to the recipient.
  • canceled: Delivery of this message was canceled, thus the message was not delivered to the recipient.
  • failed: TMS encountered an error while attempting to deliver the message to the recipeint.
  • inconclusive: TMS has attempted to deliver the message to the recipient, but has not received notification of a successful nor failed delivery.

Valid Values:

  • sending
  • sent
  • canceled
  • blacklisted
  • failed
  • inconclusive

Example

sent

Status

Body

Format: application/json

Example
{
  "url": "http://youragencysite.com/api/message_events",
  "event_type": "failed",
  "created_at": "2015-04-10T19:12:31Z",
  "_links": {
    "self": "/webhooks/21768"
  }
}
Description

Unprocessable Entity

Body

Format: application/json

Example
{
  "url":"",
  "event_type": "struck_gold",
  "created_at":null,
  "errors":{
    "url":[
      "can't be blank"
    ],
    "event_type": [
      "struck_gold is not a valid event type"
    ]
  }
}

Body

Format: application/json

Example
{
  "error": "Invalid authentication token"
}