return to Table of Contents, API

/projects/:document_identifier/webhooks

This resource supports the GET and POST methods.

URL Parameters

Label Description
:document_identifier The project's document identifier

GET

Returns an array of all the webhooks in the project.

Request Query String Parameters

Name Required Description
fields No A comma-separated list of the keys you want returned for each webhook. Default is to return all keys.

Response Status Codes

Code Description
503 Service Unavailable Server is undergoing maintenance and is unavailable
429 Rate Limited Rate limiting in effect, try again later
404 Not Found The resource could not be found or your API key has not been granted access to it
403 Forbidden Direct Mail account is disabled
401 Unauthorized API key, secret, or authentication method is incorrect
200 OK Success

Response Headers

Name Description
X-Total-Count The total number of webhooks in the project

Response Body

JSON representation of an array of objects. Each object in the array represents a webhook from the project. Please consult the /projects/:document_identifier/webhooks/:webhook_uuid resource for a description of the object keys for each webhook.

Example

GET /api/v2/projects/187812f26ba37d9769d8691d2a83c95c/webhooks HTTP/1.1
Authorization: Basic QzFENDREMjEtNTA4MC00NTM3LUFFOD
Accept: application/vnd.directmail.api+json; charset=utf-8
Host: secure.directmailmac.com

HTTP/1.1 200 OK
Date: Fri, 01 May 2015 23:33:08 GMT
Content-Type: application/json; charset=utf-8
X-Total-Count: 1

[
    {
        "date_created": "2015-05-01T12:45:17-07:00",
        "events": [
            {
                "type": "campaign-sent"
                "options": null,
            }
        ],
        "last_request_date": "2015-05-01T14:37:00-07:00",
        "last_response_status_code": 200,
        "links": [
            {
                "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/webhooks/260EB943-3D2B-419D-AC9D-063DC48681EA",
                "rel": "self"
            }
        ],
        "next_retry_date": null,
        "url": "http://requestb.in/t3e7ejt3",
        "uuid": "260EB943-3D2B-419D-AC9D-063DC48681EA"
    }
]

POST

Adds a new webhook to the project.

Request Body

A JSON object representing the webhooks.

Key Required Value Description
events Yes Array of Object Which events this webhook should be invoked on. See "Event Objects" below for a description of what each object in the array should look like.
url Yes String The URL that will be POSTed to when the webhook is invoked. See "Event Content" below for a description of what content is posted to this URL when the webhook is invoked.

Event Objects

Each event object has two keys: type and options.

The type key specifies which event the webhook should be invoked on. It should be set to one of the following values: address-inserted, address-deleted, address-updated, address-unsubscribed, address-hard-bounced, or campaign-sent. See "Event Types" below for a description of each event.

The options key specifies options that are unique to each event type. For example, the address-inserted event type requires that you specify which address group to watch for new addresses. If the event type you are interested in does not require any options, set the options key to null. See "Event Options" below for a description of what options each event type requires.

Event Types

Event Type Description
address-inserted A new address is added to an address group
address-deleted An address is deleted from an address group
address-updated An address is updated (this includes being marked as unsubscribed and/or hard bounced)
address-unsubscribed An address is marked as unsubscribed. Use this event instead of address-updated if you only care about unsubscribes.
address-hard-bounced An address is marked as hard bounced. Use this event instead of address-updated if you only care about hard bounces.
campaign-sent An email campaign finishes sending. Only available for campaigns sent via e3 Delivery Service.

Event Options

Some webhook events require that you specify additional options. For example, for the address-inserted event, you will need to specify which address group you want to watch for changes. If the event you selected does not require additional options, set the options key to null.

Event Type Options Required Options Object Keys
address-inserted Yes address_group: The UUID of the address group you want to watch for new addresses.
address-deleted Yes address_group: The UUID of the address group you want to watch for deleted addresses.
address-updated Yes address_group: The UUID of the address group you want to watch for updated addresses.
address-unsubscribed Yes address_group: The UUID of the address group you want to watch for unsubscribes.
address-hard-bounced Yes address_group: The UUID of the address group you want to watch for hard bounces.
campaign-sent No

Event Content

When your webhook is invoked, an array of one or more affected objects is JSON encoded and POSTed to the URL you provide. For a description of the keys, consult the documentation for the appropriate resource.

Event Type Resource
address-inserted /projects/:document_identifier/address-groups/:address_group_uuid/addresses/:address_uuid
address-deleted /projects/:document_identifier/address-groups/:address_group_uuid/addresses/:address_uuid
address-updated /projects/:document_identifier/address-groups/:address_group_uuid/addresses/:address_uuid
address-unsubscribed /projects/:document_identifier/address-groups/:address_group_uuid/addresses/:address_uuid
address-hard-bounced /projects/:document_identifier/address-groups/:address_group_uuid/addresses/:address_uuid
campaign-sent /projects/:document_identifier/reports/:report_uuid

Response Status Codes

Code Description
503 Service Unavailable Server is undergoing maintenance and is unavailable
429 Rate Limited Rate limiting in effect, try again later
404 Not Found The project could not be found
403 Forbidden Direct Mail account is disabled
401 Unauthorized API key, secret, or authentication method is incorrect
400 Bad Request One or more of the values in the request body is invalid
201 Created The webhook was created successfully

Response Body

A JSON object representing the new webhook. Please consult the /projects/:document_identifier/webhooks/:webhook_uuid resource for a description of the object keys for the webhook.

Example

POST /api/v2/projects/187812f26ba37d9769d8691d2a83c95c/webhooks HTTP/1.1
Authorization: Basic QzFENDREMjEtNTA4MC00NTM3LUFFOD
Content-Type: application/json
Host: secure.directmailmac.com
Connection: close
Content-Length: 135

{
    "events": [
        {
            "type": "address-unsubscribed",
            "options": {
                "address_group": "4F8956D5-03B4-473F-AD43-A818E148E89E"
            },
        }
    ],
    "url": "http://requestb.in/t3e7ejt3"
}

HTTP/1.1 201 Created
Date: Fri, 01 May 2015 23:56:40 GMT
Content-Type: application/json; charset=utf-8

{
    "date_created": "2015-05-01T16:56:40-07:00",
    "events": [
        {
            "type": "address-unsubscribed",
            "options": {
                "address_group": "4F8956D5-03B4-473F-AD43-A818E148E89E"
            }
        }
    ],
    "last_request_date": null,
    "last_response_status_code": null,
    "links": [
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/webhooks/7B0187B7-5D8E-48E2-A978-7DB9EB22CD03",
            "rel": "self"
        }
    ],
    "next_retry_date": null,
    "url": "http://requestb.in/t3e7ejt3",
    "uuid": "7B0187B7-5D8E-48E2-A978-7DB9EB22CD03"
}

Did you find this article helpful? Yes | No