x-provenance: generated: '2026-09-12' method: generated source: https://secure.agree.com/documentation#tag/Webhooks note: >- Agree.com publishes no AsyncAPI document. This one is generated faithfully from the provider's own published webhook catalog - the "Available Events" table, the payload shape, the signature headers and the retry schedule, all documented verbatim in the Webhooks tag guide of https://secure.agree.com/documentation/openapi. Every event name, description, firing condition and header below is the provider's text. No event, field, or schema has been invented. The per-event payloads reuse the Invoice and Agreement schemas from the provider's own OpenAPI, as the documentation states they do - "The payload contains the complete resource object". asyncapi: 3.0.0 info: title: Agree.com Webhooks version: 1.0.0 description: >- Real-time event notifications from the Agree contract-to-cash platform. Agree POSTs a signed JSON body to endpoints you register through POST /api/v1/webhooks. Twelve event types are published, covering the invoice lifecycle, the agreement signature lifecycle, and a test event. Delivery is at-least-once with a five-attempt exponential backoff. contact: name: Agree Support email: support@agree.com url: https://secure.agree.com/documentation externalDocs: description: Agree webhook documentation url: https://secure.agree.com/documentation#tag/Webhooks defaultContentType: application/json servers: subscriber: host: your-app.example.com protocol: https description: >- Your own HTTPS endpoint, registered via POST /api/v1/webhooks. HTTPS is required in production. Agree is the publisher; your endpoint is the server that receives. channels: webhookEndpoint: address: / title: Registered webhook endpoint description: >- The single URL you register. All subscribed event types are delivered to it with the same envelope; the event type is carried in the body's "event" member, not in the path. messages: invoiceCreated: $ref: '#/components/messages/invoiceCreated' invoiceSent: $ref: '#/components/messages/invoiceSent' invoiceDue: $ref: '#/components/messages/invoiceDue' invoicePaid: $ref: '#/components/messages/invoicePaid' invoiceFailed: $ref: '#/components/messages/invoiceFailed' invoiceCanceled: $ref: '#/components/messages/invoiceCanceled' invoiceRefunded: $ref: '#/components/messages/invoiceRefunded' agreementCreated: $ref: '#/components/messages/agreementCreated' agreementSent: $ref: '#/components/messages/agreementSent' agreementSigned: $ref: '#/components/messages/agreementSigned' agreementExecuted: $ref: '#/components/messages/agreementExecuted' webhookTest: $ref: '#/components/messages/webhookTest' operations: receiveAgreeEvent: action: receive channel: $ref: '#/channels/webhookEndpoint' title: Receive an Agree event summary: Agree POSTs a signed event envelope to your registered endpoint. description: >- Return 200 within 5 seconds and process asynchronously. Verify X-Webhook-Signature before processing. Non-2xx or timeout triggers the retry schedule. bindings: http: method: POST messages: - $ref: '#/channels/webhookEndpoint/messages/invoiceCreated' - $ref: '#/channels/webhookEndpoint/messages/invoiceSent' - $ref: '#/channels/webhookEndpoint/messages/invoiceDue' - $ref: '#/channels/webhookEndpoint/messages/invoicePaid' - $ref: '#/channels/webhookEndpoint/messages/invoiceFailed' - $ref: '#/channels/webhookEndpoint/messages/invoiceCanceled' - $ref: '#/channels/webhookEndpoint/messages/invoiceRefunded' - $ref: '#/channels/webhookEndpoint/messages/agreementCreated' - $ref: '#/channels/webhookEndpoint/messages/agreementSent' - $ref: '#/channels/webhookEndpoint/messages/agreementSigned' - $ref: '#/channels/webhookEndpoint/messages/agreementExecuted' - $ref: '#/channels/webhookEndpoint/messages/webhookTest' components: messageTraits: signedEnvelope: headers: type: object properties: Content-Type: type: string const: application/json X-Webhook-Signature: type: string description: HMAC-SHA256 of the raw request body keyed by the endpoint secret, hex, lowercase. X-Webhook-Timestamp: type: string description: Unix timestamp when the event was sent. required: - X-Webhook-Signature - X-Webhook-Timestamp schemas: envelope: type: object description: Every Agree webhook body has this two-member shape. properties: event: type: string description: The event type. payload: type: object description: The complete resource object for the event's subject. required: - event - payload invoicePayload: type: object description: >- The full Invoice resource, identical to the data member of GET /api/v1/invoices/{id}. See components.schemas.Invoice in openapi/agree-com-api-openapi.json. properties: id: type: string format: uuid status: type: string enum: - created - due - sent - canceled - paid - failed - refunded - draft amount: type: object properties: amount: type: integer description: Minor units. currency: type: string paid_at: type: string format: date-time nullable: true agreementPayload: type: object description: >- The data member of GET /api/v1/agreements/{id}, including the flat recipient fields recipients[].email and recipients[].name and field_values, a map of field_id to filled plain-text values. Nested recipients[].user and recipients[].contact objects are also included for backwards compatibility; the provider steers new integrations to the flat fields. properties: id: type: string format: uuid status: type: string recipients: type: array items: type: object field_values: type: object messages: invoiceCreated: name: invoice.created title: Invoice was created summary: Fires after POST /invoices. traits: - $ref: '#/components/messageTraits/signedEnvelope' payload: $ref: '#/components/schemas/envelope' examples: - name: invoiceCreated payload: event: invoice.created payload: id: 4a755746-ba45-4226-a669-aebc7ad3719c status: created invoiceSent: name: invoice.sent title: Invoice emailed to customer summary: Fires when delivery completes. traits: - $ref: '#/components/messageTraits/signedEnvelope' payload: $ref: '#/components/schemas/envelope' invoiceDue: name: invoice.due title: Invoice reached due status summary: >- Fires when status becomes due - either the scheduled job runs after sent (past due_at), or the invoice is sent already at or past due_at (immediate due). traits: - $ref: '#/components/messageTraits/signedEnvelope' payload: $ref: '#/components/schemas/envelope' invoicePaid: name: invoice.paid title: Payment successful summary: Fires after payment confirmation. description: >- One of the two events the provider recommends starting with - "Start with invoice.paid and invoice.failed - these are the most important for payment integrations." traits: - $ref: '#/components/messageTraits/signedEnvelope' payload: $ref: '#/components/schemas/envelope' examples: - name: invoicePaid payload: event: invoice.paid payload: id: 4a755746-ba45-4226-a669-aebc7ad3719c status: paid amount: amount: 15000 currency: USD paid_at: '2025-01-20T14:30:00Z' invoiceFailed: name: invoice.failed title: Payment attempt failed summary: >- Fires after payment rejection. The invoice status becomes failed but the customer can retry payment using the same link. traits: - $ref: '#/components/messageTraits/signedEnvelope' payload: $ref: '#/components/schemas/envelope' invoiceCanceled: name: invoice.canceled title: Invoice was canceled summary: Fires after DELETE /invoices. traits: - $ref: '#/components/messageTraits/signedEnvelope' payload: $ref: '#/components/schemas/envelope' invoiceRefunded: name: invoice.refunded title: Invoice payment was refunded summary: Fires after a refund is processed. description: >- Note that no refund OPERATION exists in the REST API. This event is emitted for refunds performed outside the API surface. traits: - $ref: '#/components/messageTraits/signedEnvelope' payload: $ref: '#/components/schemas/envelope' agreementCreated: name: agreement.created title: Agreement was created summary: Fires after POST /agreements. traits: - $ref: '#/components/messageTraits/signedEnvelope' payload: $ref: '#/components/schemas/envelope' agreementSent: name: agreement.sent title: Agreement was sent to recipients summary: Fires when status changes to sent. traits: - $ref: '#/components/messageTraits/signedEnvelope' payload: $ref: '#/components/schemas/envelope' agreementSigned: name: agreement.signed title: Agreement was signed by a recipient summary: Fires when a recipient signs. Emitted once per signer. traits: - $ref: '#/components/messageTraits/signedEnvelope' payload: $ref: '#/components/schemas/envelope' agreementExecuted: name: agreement.executed title: Agreement was fully executed summary: Fires when all signers have signed. traits: - $ref: '#/components/messageTraits/signedEnvelope' payload: $ref: '#/components/schemas/envelope' webhookTest: name: webhook.test title: Test event summary: Fires when you trigger a test via POST /api/v1/webhooks/test. traits: - $ref: '#/components/messageTraits/signedEnvelope' payload: $ref: '#/components/schemas/envelope' x-delivery: semantics: at-least-once duplicates: >- Documented as possible - "Webhooks may occasionally be sent more than once; use idempotency." retry_schedule: - attempt: 1 delay: immediate - attempt: 2 delay: ~1 minute - attempt: 3 delay: ~5 minutes - attempt: 4 delay: ~30 minutes - attempt: 5 delay: ~2 hours after_exhaustion: >- The webhook is marked failed and the endpoint's failure_count is incremented. The provider recommends monitoring failure_count to detect integration issues. response_deadline: Return 200 within 5 seconds, then process asynchronously. x-management: register: POST /api/v1/webhooks list: GET /api/v1/webhooks show: GET /api/v1/webhooks/{id} update: PUT|PATCH /api/v1/webhooks/{id} delete: DELETE /api/v1/webhooks/{id} test: POST /api/v1/webhooks/test disable: Set active to false rather than deleting. secret: >- A whsec_-prefixed signing secret is returned exactly once, in the create response, and cannot be retrieved afterwards. path_note: >- The prose documentation writes these paths as /api/v1/webhook_endpoints; the OpenAPI declares /api/v1/webhooks. The OpenAPI paths are used here. See conventions/agree-com-conventions.yml, documentation_defects.