> ## Documentation Index > Fetch the complete documentation index at: https://docs.dintero.com/llms.txt > Use this file to discover all available pages before exploring further. ## Submitting Feedback If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback: POST https://docs.dintero.com/feedback ```json { "path": "/api-reference/subscriptions/create-new-subscription", "feedback": "Description of the issue" } ``` Only submit feedback when you have something specific and actionable to report. # Create new subscription > When you create a new webhook, we'll send you a simple ping event to let you know you've set up the webhook correctly. You can trigger a ping again by calling the [ping endpoint](#operation/aid_source_hooks_hid_ping_post). ## Receiving Webhooks In order for Dintero to send webhook payloads, your server needs to be accessible from the Internet. We also highly suggest using SSL so that we can send encrypted payloads over HTTPS. ## Respond to a webhook Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the 200 range will let Dintero know that you did not receive your webhook, including 301 Redirect. Dintero does not follow redirects for webhook notifications and will consider a redirection as an error response. Dintero has implemented a 60-second timeout period and a retry period for subscriptions. We wait 120 seconds for a response to each request, and if there isn't one or we get an error, we retry the connection to a total of 5 times. A webhook will be deleted if there are consecutive failures for the exact same webhook. You should monitor the admin of your webhook tool for failing webhooks. ### Webhooks Headers Dintero will send along several HTTP headers to differentiate between event types and payload identifiers. | Name | Description | |----------------|------------------------------------------------------| | event | The event type | | event-delivery | A guid to indentify the payload and event being sent | | event-signature| The value of this header is computed as the HMAC SHA1 hex digest of the body, using the secret config option as the key. | scopes: - admin:hooks - write:hooks ## OpenAPI ````yaml /mintlify-docs/openapi/spec-webhooks.yaml post /accounts/{aid}/hooks/subscriptions openapi: 3.0.0 info: title: Hooks API description: > API for managing webhooks # Changelog All notable changes to the API. ## 2026-03-10 > **Update**: Switch from `external_token_reference` to `external_token_references` for card tokens > - [Event example](#operation/example_checkout_token_event) ## 2026-03-01 > **doc**: Document guaranteed fields in card token event payloads > - [Event example](#operation/example_checkout_token_event) ## 2026-02-18 > **Update**: Document support for `external_token_reference` for card tokens > - [Event example](#operation/example_checkout_token_event) ## 2026-01-26 > **new**: Add support for subscription on `account_location_add`, > `account_location_update` and `account_location_delete` events. > > - [POST hooks/subscriptions](#operation/aid_source_hooks_post) > - [Event example](#operation/example_account_location_add_event) ## 2025-11-30 > **new**: Add support for `exclude_fields` in webhooks. Use the new option > to exclude fields from the event being delivered > - [POST hooks/subscriptions](#operation/aid_source_hooks_post) > **new**: Add support for subscription on `checkout_authorization` event. > > - [POST hooks/subscriptions](#operation/aid_source_hooks_post) > - [Event example](#operation/example_checkout_authorization_event) ## 2025-10-01 > **new**: Add support for subscription on `checkout_token_add`, > `checkout_token_update` and `checkout_token_delete` event. > > - [POST hooks/subscriptions](#operation/aid_source_hooks_post) > - [Event example](#operation/example_checkout_token_event) ## 2024-08-01 > **update**: Extend the `cdd_case_update` event with optional > `payout_destination_case` and `payment_case` to make it easier to determine > what CDD case was updated > - [Event example](#operation/example_cdd_case_update_event) ## 2024-02-01 > **doc**: Fix `HookDeliveryDetail` definition, the type for the `response.body` > and `details.delivery_duration` was wrong, change to `string` and > `number` > - [GET /v1/accounts/{aid}/hooks/subscriptions/{hid}/deliveries/{delivery_id}](#operation/aid_source_hooks_hid_deliveries_did_get) ## 2023-12-01 > **new**: Add support for `approval_payout_destination_delete` event. > The event will be published when a seller approval is archived > - [POST hooks/subscriptions](#operation/aid_source_hooks_post) > - [Event example](#operation/example_approval_payout_destination_update_delete) ## 2023-01-01 > **new**: Add support for subscription on `checkout_transaction` event. > - [POST hooks/subscriptions](#operation/aid_source_hooks_post) > - [Event example](#operation/example_checkout_transaction_event) ## 2022-11-01 > Add support for creating subscription with `fields` mask. The fields property > lets you explicitly select the fields you need from the event deliveries > - [POST hooks/subscriptions](#operation/aid_source_hooks_post) ## 2022-08-01 > Document example for `approval_payout_destination_update` event > - [POST approval_payout_destination_update event](#operation/example_approval_payout_destination_update_event) ## 2021-04-01 > Add support for subscription on `shopping_order_delete` events. > - [POST hooks/subscriptions](#operation/aid_source_hooks_post) ## 2021-01-01 > Add support for subscription on `settlement_add` events. > - [POST hooks/subscriptions](#operation/aid_source_hooks_post) ## 2020-10-01 > Add support for subscription on `account_add` and `account_update` events. > - [POST hooks/subscriptions](#operation/aid_source_hooks_post) ## 2019-04-31 > Implement support for subscription on > `discount_customer_update` event. The event is published after a > - [POST hooks/subscriptions](#operation/aid_source_hooks_post) > `receipt_add` event or when discounts are claimed. # Webhook Events Each event has a similar JSON schema, but a unique payload object that is determined by its event type. ## Accounts ### account_add / account_update The event is sent from auth service after an account is added or updated. > The events are only available for production subscriptions > `account_add` events are only available for partner accounts POST / User-Agent: Dintero-Hook/0c9ad03b Content-Type: application/json event: account_add event-delivery: cfedde7e-b088-415e-ad5b-cbe54acbb6f9 { "account_id": "P12341234", "event": "account_add", "event_delivery": "cfedde7e-b088-415e-ad5b-cbe54acbb6f9", "account": { "account_id": "12341234", "jwks": { "name": "example", "uri": "https://example.com" }, "applicant": { "agreement": { "accepted_at": "2022-01-01T00:00:00Z" }, "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone_number": "+1234567890", "promo_code": "ABC123", "utm": { "utm_source": "google", "utm_medium": "cpc", "utm_campaign": "example" } }, "billing": { "address": { "address_line": "123 Main St", "postal_place": "MainVille", "country": "NO" }, "business_name": "Example Inc" }, "company": { "business_name": "Example Inc.", "address": { "address_line": "123 Main St", "postal_place": "MainVille", "country": "NO" } }, "language_code": "en-US", "livemode": "true", "partner_id": "00000000", "active": "true", "account_manager": { "email": "jane.doe@example.com" }, "reseller_id": "reseller123", "progression": "live", "subscription": { "interval": "month", "metadata": { "key": "value" }, "plan": "basic", "support": "email" }, "services": { "checkout": { "enabled": "true", "settings": { "key": "value" } }, "customers": { "enabled": "true", "settings": { "key": "value" } } }, "connections": { "collector": { "invoice": { "enabled": "true", "settings": { "key": "value" } } } }, "created_by": "1234-1234-1234-1234" } } ### account_location_add / account_location_update / account_location_delete The event is sent from auth service after an account location is added, updated or deleted. POST / User-Agent: Dintero-Hook/0c9ad03b Content-Type: application/json event: account_location_add event-delivery: cfedde7e-b088-415e-ad5b-cbe54acbb6f9 { "account_id": "P12341234", "event": "account_location_add", "event_delivery": "cfedde7e-b088-415e-ad5b-cbe54acbb6f9", "location": { "id": "T12341234-0001", "location_id": "STORE001", "location_name": "Main Store", "created_at": "2019-08-24T14:15:22Z", "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e", "updated_at": "2019-08-24T14:15:22Z", "updated_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e", "status": "ACTIVE", "verified": true, "number_of_terminals": 2, "organization": { "organization_number": "123456789", "name": "Example Company AS", "trade_name": "Example Store" }, "email": "store@example.com", "phone_number": "+4799999999", "address": { "address_line": "Sommerkroveien 34", "postal_place": "Oslo", "postal_code": "0349", "country": "NO" }, "payout_destination": { "payout_destination_id": "pd-123", "status": "ACTIVE", "type": "company" }, "operator_payout_destinations": [] } } ## Customers ### customer_update / customer_add / customer_delete Customer event sent from customers service after a customer is created, updated or deleted. All customer properties will be included in the event. POST / User-Agent: Dintero-Hook/0c9ad03b Content-Type: application/json event: customer_update event-delivery: cfedde7e-b088-415e-ad5b-cbe54acbb6f9 { "account_id": "P12341234", "event": "customer_update", "event_delivery": "cfedde7e-b088-415e-ad5b-cbe54acbb6f9", "metadata": { "dob_year": 1985 }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "created_at": "2019-08-24T14:15:22Z", "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e", "updated_at": "2019-08-24T14:15:22Z", "first_name": "John", "last_name": "Doe", "email": "customer@example.com", "phone_number": "+4799999999", "status": "string", "favorite_store": "string", "enrolled_by": { "type": "url", "value": "https://facebook.com" }, "type": "customer", "addresses": [ { "address_line": "Sommerkroveien 34", "postal_place": "Oslo", "country": "NO" } ], "term": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "accepted_at": "2019-08-24T14:15:22Z" }, "company": { "organization_number": "123456789MVA", "bussiness_name": "TKP tech AS", "department": "sales department", "industry": "computer industry", }, "date_of_birth": "1990-09-20", "customer_id": "string" } ### customer_change_password Customer event sent from customers service after a change_password request is received. Note that the event includes a context object with `audience` and `created_by`. POST / User-Agent: Dintero-Hook/0c9ad03b Content-Type: application/json event: customer_change_password event-delivery: cfedde7e-b088-415e-ad5b-cbe54acbb6f9 { "account_id": "P12341234", "event": "customer_change_password", "event_delivery": "cfedde7e-b088-415e-ad5b-cbe54acbb6f9", "metadata": { "dob_year": 1985 }, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "created_at": "2019-08-24T14:15:22Z", "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e", "updated_at": "2019-08-24T14:15:22Z", "first_name": "John", "last_name": "Doe", "email": "customer@example.com", "phone_number": "+4799999999", "status": "string", "favorite_store": "string", "enrolled_by": { "type": "url", "value": "https://facebook.com" }, "type": "customer", "addresses": [ { "address_line": "Sommerkroveien 34", "postal_place": "Oslo", "country": "NO" } ], "term": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "accepted_at": "2019-08-24T14:15:22Z" }, "company": { "organization_number": "123456789MVA", "bussiness_name": "TKP tech AS", "department": "sales department", "industry": "computer industry", }, "date_of_birth": "1990-09-20", "customer_id": "string" "context": { "audience": "https://api.dintero.com/v1/accounts/P00000000", "created_by": "API_USER" } } ## Discounts ### discount_update / discount_add / discount_delete Discount event sent from discount service after a discount rule is created, updated or deleted. All discount properties will be included in the event POST / User-Agent: Dintero-Hook/0c9ad03b Content-Type: application/json event: discount_update event-delivery: cfedde7e-b088-415e-ad5b-cbe54acbb6f9 { "account_id": "P12341234", "event": "discount_update", "event_delivery": "cfedde7e-b088-415e-ad5b-cbe54acbb6f9", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "created_at": "2019-08-24T14:15:22Z", "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e", "updated_at": "2019-08-24T14:15:22Z", "campaign_id": "string", "active": "true", "private": "false", "updated_by": "3d1e4824-5474-48e7-a369-4f603fa4c5b8", "type": "item", "name": "Spar 100,-", "receipt_text": "Mai Salg", "visible_from": "2019-08-24T14:15:22Z", "description": "Gjør et Stablestol kupp!", "limitation": { "discount_activation": [ { "type": "deactivate_if_discount_active", "value": "string" } ], "discount_hours": { "timezone": "Europe/Oslo", "hours": [ { "day": "mon", "start": "10:00", "end": "20:00" } ] }, "discount_reward_usage": 1, "discount_combination": -1, "discount_eligible": "item_eligible_for_discount", "discount_repeat_usage": -1, "stamp_expire_days": 100, "blacklist": [ { "id": "b714118", "group_id": "B1" } ] }, "requirement": { "customer": { "addresses": [ { "country": [ "NO" ], "postal_code": [ "0349" ], "postal_place": [ "Oslo" ], "custom_type": [ "offsite" ], "type": [ "custom" ] } ], "company": { "bussiness_name": [ "TKP tech AS" ], "department": [ "production", "research" ], "industry": [ "J62.0.1", "J62.0.2" ], "number_of_employees": [ "20" ], "organization_number": [ "123456789MVA" ], "website": [ "https://dintero.com" ] }, "date_of_birth": [ "1990-09-20", "1990-05-10" ], "first_name": [ "John" ], "gender": [ "male" ], "last_name": [ "Doe" ], }, "item": { "quantity": 0, "mixes": [ { "items": [ { "id": "b714118" }, { "group_id": "g4" } ], "quantity": 0, "reward_eligible": "true" } ], "items": [ { "id": "b714118", "group_id": "B1" } ] }, "store_ids": [ "sc029" ], "gross_amount": 0, "currencies": [ { "anything-but": [ "NOK" ] } ], "stamp": 5, "discount_code": "TACO", "store": { "id": [ "sc029" ], }, "purchase_from": "2019-08-24T14:15:22Z", "purchase_to": "2019-08-24T14:15:22Z" }, "reward": { "type": "discount_amount", "value": 10000, "base": "net", "effect": "discount" }, "metadata": { "campaign_id": "V101", "is_featured": "true", "dintero:private_text:kind": "Gold" }, "links": [ { "href": "https://example.dintero.com/c/photos/2018/6_20_thumbnail_discount_image.png", "rel": "thumbnail_discount_image" } ] } ### discount_add_customers / discount_delete_customers The event is sent from discount service after a customer is added removed from the discount. The event will originate from [Add customer](https://docs.dintero.com/api.html#tag/rules-customers/operation/aid_discounts_did_customers_post), [Remove customer](https://docs.dintero.com/api.html#tag/rules-customers/operation/aid_discounts_did_customers_delete) or from an [automation](https://docs.dintero.com/api.html#tag/rules-automations/operation/aid_automations_rules_post) triggered. The receipt/automation property is only set if the customer was added to the discount by the automation. POST / User-Agent: Dintero-Hook/0c9ad03b Content-Type: application/json event: discount_add_customers event-delivery: cfedde7e-b088-415e-ad5b-cbe54acbb6f9 { "account_id": "P12341234", "event": "discount_add_customers", "event_delivery": "cfedde7e-b088-415e-ad5b-cbe54acbb6f9", "created_at": "2018-01-10T08:49:20.533Z", "created_by": "API_USER", "id": "{customer_ref_discount_id}", "customer_id": "{customer_id}", "discount": { "id": "{discount.id}" }, "receipt": { "id": "{receipt.id}" ... }, "automation": { "created_at": "2018-03-19T15:04:42Z", "created_by": "API_USER", "id": "string", "updated_at": "2018-03-19T15:04:42Z", "events": ["customer_add"] } } ### discount_customer_update The event is sent from discount service after a customer discounts is updated. An update is triggered when discounts are used (receipt_add), claimed or if stamp is added to the discount (receipt_add). POST / User-Agent: Dintero-Hook/0c9ad03b Content-Type: application/json event: discount_customer_update event-delivery: cfedde7e-b088-415e-ad5b-cbe54acbb6f9 { "account_id": "P12341234", "event": "discount_customer_update", "event_delivery": "cfedde7e-b088-415e-ad5b-cbe54acbb6f9", "created_by": "string", "created_at": "2022-01-01T00:00:00Z", "customer_id": "string", "claim": { "id": "string" }, "receipt": { "id": "string" }, "discounts": [ { "id": "string", "refs": [ { "id": "string", "stamp": 1337, "amount": 10, "usage": 1, "bonus": 0, "statistics": { "amount": 10, "bonus": 0, "debit_balance": 0, "stamp": 1640995200, "usage": 1 } } ] } ] } ## Locations ### location_add / location_update / location_delete Location event sent from our customer service after a location is created, updated or deleted. All locations properties will be included in the event. POST / User-Agent: Dintero-Hook/0c9ad03b Content-Type: application/json event: location_add event-delivery: cfedde7e-b088-415e-ad5b-cbe54acbb6f9 { "account_id": "P12341234", "event": "location_add", "event_delivery": "cfedde7e-b088-415e-ad5b-cbe54acbb6f9", "location": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "created_at": "2019-08-24T14:15:22Z", "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e", "updated_at": "2019-08-24T14:15:22Z", "location_id": "S01923", "name": "TKP Store", "timezone": "Europe/Oslo", "status": "Active", "language_code": "string", "currency": "NOK", "phone_number": "+4799999999", "chain": "SuperChain", "email": "saleslocation@example.com", "mcc": "5814", "gln": "string", "organization_number": "123456789MVA", "business_name": "TKP technology AS", "franchise": "Subway", "type": "string", "website_url": "string", "address": { "address_line": "Sommerkroveien 34", "address_line_2": "PB 123", "postal_code": "0349", "postal_place": "Oslo", "country": "NO", "latitude": 0, "longitude": 0 } } } ## Receipts ### receipt_add / receipt_update Receipt event sent from receipts service after a receipt is added. The complete receipt will be included in the event. POST / User-Agent: Dintero-Hook/0c9ad03b Content-Type: application/json event: receipt_add event-delivery: cfedde7e-b088-415e-ad5b-cbe54acbb6f9 { "account_id": "P12341234", "event": "receipt_add", "event_delivery": "cfedde7e-b088-415e-ad5b-cbe54acbb6f9", "created_at": "2018-01-10T07:57:42Z", "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e", "id": "2adb53e8-7f9b-44a4-8d5f-ed85d44cf02b", "purchase_at": "2018-01-10T07:57:42Z", "receipt_id": "714118", "store": { "id": "sc029" } } ## Settlements ### settlement_add POST / User-Agent: Dintero-Hook/0c9ad03b Content-Type: application/json event: settlement_add event-delivery: cfedde7e-b088-415e-ad5b-cbe54acbb6f9 { "account_id": "P12341234", "event": "settlement_add", "event_delivery": "cfedde7e-b088-415e-ad5b-cbe54acbb6f9", "settlement": { "id": "string", "account_id": "P12341234", "settled_at": "2022-01-01T00:00:00.000Z", "email_received_at": "2022-01-02T00:00:00.000Z", "gateway": "vipps", "created_at": "2022-01-03T00:00:00.000Z", "updated_at": "2022-01-04T00:00:00.000Z", "provider_reference": "123456789", "payout_destination_id": "987654321", "metadata": { "attachments": [ { "id": "attachment1", "download_link": "https://example.com/attachment1", "content_type": "application/pdf", "extension": "pdf", "created_by": "user1" } ], "aggregation": [ { "capture": 94000, "amount": 30825, "currency": "NOK", "fee": -1175, "refund": -62000 } ], "start_at": "2022-01-01T00:00:00.000Z", "end_at": "2022-01-02T00:00:00.000Z" } } } ## Shopping ### shopping_draft_add / shopping_draft_complete / shopping_draft_update POST / User-Agent: Dintero-Hook/0c9ad03b Content-Type: application/json event: shopping_draft_add event-delivery: cfedde7e-b088-415e-ad5b-cbe54acbb6f9 { "account_id": "P12341234", "event": "shopping_draft_add", "event-delivery": "cfedde7e-b088-415e-ad5b-cbe54acbb6f9", "options": { "order_time_to_live": 94672800, "generate_order_id": "UUID", "order_id": "string", "replace": "order", "split_draft": "false", "serial_order_number_suffix": "false", "multiple_authorizations": "false" }, "order": { "customer": { "first_name": "John", "last_name": "Doe", "id": "string", "email": "customer@example.com", "phone_number": "+4799999999", "addresses": [ { "address_line": "Sommerkroveien 34", "postal_place": Oslo, "country": "NO" } ], "enrolled_by": { "type": "url", "value": "https://facebook.com" }, "type": "customer" }, "shipping_address": { "address_line": "Sommerkroveien 34", "postal_place": "Oslo", "country": "NO" }, "billing_address": { "address_line": "Sommerkroveien 34", "postal_place": "Oslo", "country": "NO" }, "comment": "string", "salesperson_id": "string", "salesperson_name": "string", "delivery_at": "2019-08-24T14:15:22Z", "pickup_at": "2019-08-24T14:15:22Z", "courier_id": "string", "pre_order": "true", "time_to_live": 94672800, "items": [ { "status": "string", "id": "175938", "groups": [ { "id": "B234", "name": "Stol" }, { "id": "B1", "name": "Møbel" } ], "line_id": 1, "quantity": 2, "gross_amount": 39800, "tax_lines": [ { "amount": 5584, "percentage": 25, "tax_code": "3", "tax_group": "Vmva-høy" } ], "description": "Stablestol for utendørsbruk", "eligible_for_discount": "true", "discount_lines": [ { "amount": 23130, "percentage": 10, "discount_type": "customer", "discount_id": "766da0ef-9283-42bd-b012-0582344ec53c", "description": "string", "line_id": 1 } ] } ], "type": "delivery", "order_number": "order123456", "currency": "NOK", "order_id": "string", "store": { "id": "SL02" } } } ### shopping_order_update / shopping_order_event_add / shopping_order_delete POST / User-Agent: Dintero-Hook/0c9ad03b Content-Type: application/json event: shopping_order_update event-delivery: cfedde7e-b088-415e-ad5b-cbe54acbb6f9 { "account_id": "P12341234", "event": "shopping_order_update", "event-delivery": "cfedde7e-b088-415e-ad5b-cbe54acbb6f9", "customer": { "first_name": "John", "last_name": "Doe", "id": "string", "email": "customer@example.com", "phone_number": "+4799999999", "addresses": [ { "address_line": "Sommerkroveien 34", "postal_place": "Oslo", "country": "NO" } ], "status": "string", "type": "customer" }, "shipping_address": { "address_line": "Sommerkroveien 34", "postal_place": "Oslo", "country": "NO" }, "billing_address": { "address_line": "Sommerkroveien 34", "postal_place": "Oslo", "country": "NO" }, "delivery_at": "2019-08-24T14:15:22Z", "pickup_at": "2019-08-24T14:15:22Z", "courier_id": "string", "items": [ { "status": "string", "line_id": 1 } ] } ## Wallet ### wallet_transaction Wallet transaction event sent from wallets service after a transaction is created POST / User-Agent: Dintero-Hook/0c9ad03b Content-Type: application/json event: wallet_transaction event-delivery: cfedde7e-b088-415e-ad5b-cbe54acbb6f9 { "event": "wallet_transaction", "event_delivery": "cfedde7e-b088-415e-ad5b-cbe54acbb6f9", "created_at": "2017-11-30T08:12:20.533Z", "created_by": "API_USER", "id": "19657e92-9165-4b4f-92ab-2cd9cdef1525", "metadata": { }, "ref_id": "0000359382", "amount": 69900, "currency": "NOK", "parent_id": null, "type": "drawdown", "account_id": "T00000000", "card_id": "1234567890" } contact: name: API Integration Support email: integration@dintero.com version: LATEST license: name: UNLICENSED url: https://dintero.com servers: - url: https://api.dintero.com/v1 security: - JWT: [] tags: - name: example-management-auth-events x-displayName: Accounts description: Accounts events - name: example-checkout-events x-displayName: Checkout description: Checkout events paths: /accounts/{aid}/hooks/subscriptions: post: tags: - subscriptions summary: Create new subscription description: > When you create a new webhook, we'll send you a simple ping event to let you know you've set up the webhook correctly. You can trigger a ping again by calling the [ping endpoint](#operation/aid_source_hooks_hid_ping_post). ## Receiving Webhooks In order for Dintero to send webhook payloads, your server needs to be accessible from the Internet. We also highly suggest using SSL so that we can send encrypted payloads over HTTPS. ## Respond to a webhook Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the 200 range will let Dintero know that you did not receive your webhook, including 301 Redirect. Dintero does not follow redirects for webhook notifications and will consider a redirection as an error response. Dintero has implemented a 60-second timeout period and a retry period for subscriptions. We wait 120 seconds for a response to each request, and if there isn't one or we get an error, we retry the connection to a total of 5 times. A webhook will be deleted if there are consecutive failures for the exact same webhook. You should monitor the admin of your webhook tool for failing webhooks. ### Webhooks Headers Dintero will send along several HTTP headers to differentiate between event types and payload identifiers. | Name | Description | |----------------|------------------------------------------------------| | event | The event type | | event-delivery | A guid to indentify the payload and event being sent | | event-signature| The value of this header is computed as the HMAC SHA1 hex digest of the body, using the secret config option as the key. | scopes: - admin:hooks - write:hooks operationId: aid_source_hooks_post parameters: - $ref: '#/components/parameters/accountId' requestBody: content: application/json: schema: $ref: '#/components/schemas/Hook' description: subscription configuration required: true responses: '200': description: Subscription created content: application/json: schema: $ref: '#/components/schemas/Hook' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AccessForbidden' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' security: - JWT: [] components: parameters: accountId: name: aid description: | An id that uniquely identifies the account. in: path required: true schema: type: string format: ^[PT]{1}\d{8}$ minLength: 9 maxLength: 9 schemas: Hook: type: object description: | Configuration for a webhook allOf: - $ref: '#/components/schemas/Entity' - required: - config - events properties: active: type: boolean description: | Determines whether the hook is actually triggered. default: true config: type: object required: - url properties: url: type: string description: | A required string defining the URL to which the payloads will be delivered. The URL must be public available and you cannot use the following as value: - localhost - "fake" domains like www.example.com - Dintero domains (i.e. dintero.com) content_type: type: string default: application/json enum: - application/json secret: $ref: '#/components/schemas/Secret' insecure_ssl: type: integer description: | An optional string that determines whether the SSLcertificate of the host for url will be verified when delivering payloads. Supported values include `"0"` (verification is performed) and `"1"` (verification is not performed). The default is `"0"`. default: 0 fields: type: string description: | Limit the event data included in the delivery The syntax is loosely based on XPath: - a,b,c comma-separated list will select multiple fields - a/b/c path will select a field from its parent - a(b,c) sub-selection will select many fields from a parent - a/*/c the star * wildcard will select all items in a field example: account(partner_id,account_id,created_at) format: field-mask exclude_fields: type: array description: | Limit the event data included in the delivery example: - customer_ip - billing_address items: type: string minItems: 1 maxItems: 20 maxLength: 50 format: field-name events: type: array items: type: string minItems: 1 enum: - account_add - account_update - account_store_add - account_store_update - account_store_delete - receipt_add - receipt_update - customer_add - customer_update - customer_delete - customer_change_password - token_add - token_remove - transaction - wallet_transaction - discount_add - discount_update - discount_delete - discount_add_customers - discount_customer_update - shopping_draft_add - shopping_draft_update - shopping_draft_complete - shopping_order_update - shopping_order_event_add - shopping_order_delete - settlement_add - location_add - location_delete - location_update - cdd_case_update - approval_payout_destination_update - approval_payout_destination_delete - checkout_authorization - checkout_transaction - checkout_token_add - checkout_token_update - checkout_token_delete Entity: type: object properties: id: type: string format: uuid description: | An UUID that uniquely identifies the resource readOnly: true created_at: type: string format: date-time description: | The date-time when the resource was created readOnly: true created_by: type: string example: 1c92f7e1-2897-4d46-bdcc-c127a914fb4e description: | The ID of the user/client created the resource readOnly: true updated_at: type: string format: date-time description: | The date-time when the resource was last updated readOnly: true deleted_by: type: string example: 1c92f7e1-2897-4d46-bdcc-c127a914fb4e description: | The ID of the user/client created the resource readOnly: true deleted_at: type: string format: date-time readOnly: true Secret: type: object discriminator: propertyName: type required: - type properties: type: type: string enum: - HMAC-SHA1 - AWS4-HMAC-SHA256 - Authorization Error: type: object required: - error properties: error: type: object required: - message properties: code: type: string description: The code used to identify the error/warning errors: type: array description: The nested error(s) encountered during validation items: type: object message: type: string description: The human readable description of the error/warning responses: BadRequest: description: Bad / Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' AccessForbidden: description: Access forbidden, invalid JWT token was used content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' ServerError: description: Unexpected Error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: JWT: type: http description: > Bearer authentication (token authentication) should be used for accessing the API. Use [Get Token](https://docs.dintero.com/api.html#operation/aid_auths_oauth_token_post) to get an access token for client credentials. Pass the token in the request header: Authorization: Bearer {access_token} where the **access_token** is JSON Web Tokens (JWT). scheme: bearer bearerFormat: JWT ````